Quickstart

Create a verification

Make a POST request to create a verification session. You do not list the checks: the default workflow for the country decides them. This example assumes a workflow with a face scan and a document scan.

curl -X POST https://api.pawapass.com/v2/verifications/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "externalId": "user-zm-98765",
    "phoneNo": "+260971234567",
    "country": "ZM",
    "metadata": {
      "reason": "kyc-onboarding",
      "channel": "mobile-app",
      "department": "compliance"
    },
    "successUrl": "https://your-website.com/success",
    "errorUrl": "https://your-website.com/error",
    "supportUrl": "https://your-website.com/support",
    "createdBy": "[email protected]"
  }'

const response = await fetch('https://api.pawapass.com/v2/verifications/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
  },
  body: JSON.stringify({
    externalId: 'user-zm-98765',
    phoneNo: '+260971234567',
    country: 'ZM',
    metadata: {
      reason: 'kyc-onboarding',
      channel: 'mobile-app',
      department: 'compliance',
    },
    successUrl: 'https://your-website.com/success',
    errorUrl: 'https://your-website.com/error',
    supportUrl: 'https://your-website.com/support',
    createdBy: '[email protected]',
  }),
});

const verification = await response.json();
console.log(verification.url); // Redirect user here

import requests

response = requests.post(
    "https://api.pawapass.com/v2/verifications/",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY",
    },
    json={
        "externalId": "user-zm-98765",
        "phoneNo": "+260971234567",
        "country": "ZM",
        "metadata": {
            "reason": "kyc-onboarding",
            "channel": "mobile-app",
            "department": "compliance",
        },
        "successUrl": "https://your-website.com/success",
        "errorUrl": "https://your-website.com/error",
        "supportUrl": "https://your-website.com/support",
        "createdBy": "[email protected]",
    },
)

verification = response.json()
print(verification["url"])  # Redirect user here

The response includes a url field. Redirect the user there:

{
  "id": "aB1cD2eF",
  "externalId": "user-zm-98765",
  "phoneNo": "+260971234567",
  "country": "ZM",
  "workflowId": null,
  "url": "https://app.pawapass.com/your-company/aB1cD2eF",
  "status": "CREATED",
  "requirements": [
    { "type": "FACE_SCAN" },
    { "type": "DOCUMENT_SCAN" }
  ],
  "metadata": {
    "reason": "kyc-onboarding",
    "channel": "mobile-app",
    "department": "compliance"
  },
  "identityDocument": null,
  "createdBy": "[email protected]",
  "expiresAt": "2025-08-09T14:00:00.000Z",
  "createdAt": "2025-07-10T14:00:00.000Z",
  "updatedAt": "2025-07-10T14:00:00.000Z"
}

Verifications are deduplicated by externalId. When you create a verification, pawaPass checks for an existing active verification with the same externalId:

No active verification exists: a new verification is created and the response status is 201 Created.
An active verification already exists: the existing verification is returned unchanged and the response status is 200 OK. A new verification is not created.

A verification is considered active until it reaches a final status (APPROVED, DECLINED, or EXPIRED). Once the previous verification is in a final status, creating a verification with the same externalId starts a fresh one (201 Created). If short links are enabled, the new verification reuses the same url as the previous one, so the link you shared earlier keeps pointing to the latest verification.

Get Started

Guides

Prerequisites

Next steps

​Prerequisites

​Next steps

Prerequisites

Next steps