Skip to main content

​
Prerequisites

  • A pawaPass partner account
  • An API key (contact us to obtain one)
1

Create a verification

Make a POST request to create a verification session. This example creates a full KYC onboarding flow with document scan and face verification:
curl -X POST https://api.pawapass.com/v2/verifications/ \
  -H "Content-Type: application/json" \
  -H "X-AUTH-KEY: YOUR_API_KEY" \
  -d '{
    "externalId": "user-zm-98765",
    "phoneNo": "+260971234567",
    "country": "ZM",
    "requirements": [
      { "type": "DOCUMENT_SCAN" },
      { "type": "FACE_SCAN" }
    ],
    "metadata": {
      "jurisdiction": "ZM",
      "reason": "kyc-onboarding"
    },
    "successUrl": "https://your-website.com/success",
    "errorUrl": "https://your-website.com/error",
    "supportUrl": "https://your-website.com/support",
    "createdBy": "[email protected]"
  }'
The response includes a url field — redirect the user there:
{
  "id": "aB1cD2eF",
  "externalId": "user-zm-98765",
  "phoneNo": "+260971234567",
  "country": "ZM",
  "url": "https://app.pawapass.com/your-company/aB1cD2eF",
  "status": "CREATED",
  "requirements": [
    { "type": "DOCUMENT_SCAN" },
    { "type": "FACE_SCAN" }
  ],
  "metadata": {
    "jurisdiction": "ZM",
    "reason": "kyc-onboarding"
  },
  "identityDocument": null,
  "createdBy": "[email protected]",
  "expiresAt": "2025-07-11T14:00:00Z",
  "createdAt": "2025-07-10T14:00:00Z",
  "updatedAt": "2025-07-10T14:00:00Z"
}
2

Redirect the user

Send the user to the url from the response. They will complete the document scan and face scan in the pawaPass verification flow.After completion, the user is redirected to your successUrl or errorUrl.
3

Check the result

Fetch the verification to see the status and extracted document data:
curl https://api.pawapass.com/v2/verifications/aB1cD2eF \
  -H "X-AUTH-KEY: YOUR_API_KEY"
When the status is APPROVED, the identityDocument field contains the extracted data:
{
  "id": "aB1cD2eF",
  "status": "APPROVED",
  "identityDocument": {
    "type": "Government Issued Photo ID",
    "country": "Zambia",
    "serialNo": "9876543/21/1",
    "nationalNo": "Z12345678",
    "firstName": "Tisa",
    "lastName": "Banda",
    "dateOfBirth": "1997-05-10",
    "placeOfBirth": "Lusaka",
    "nationality": "ZM",
    "expiryAt": "2032-05-09",
    "issuedAt": "2022-05-10",
    "issuingAuthority": "Republic of Zambia",
    "placeOfIssue": "Lusaka"
  }
}

​
Next steps