Skip to main content
POST
/
verifications
cURL
curl --request POST \
  --url https://api.pawapass.com/v2/verifications/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "user-zm-98765",
  "requirements": [
    {
      "type": "DOCUMENT_SCAN"
    },
    {
      "type": "FACE_SCAN"
    }
  ],
  "successUrl": "https://your-website.com/success",
  "errorUrl": "https://your-website.com/error",
  "supportUrl": "https://your-website.com/support",
  "country": "ZM",
  "phoneNo": "+260971234567",
  "metadata": {
    "reason": "kyc-onboarding",
    "channel": "mobile-app",
    "department": "compliance"
  },
  "expiresAt": "2025-08-27T09:00:00.000Z",
  "createdBy": "[email protected]"
}
'
{
  "id": "aB1cD2eF",
  "externalId": "user-zm-98765",
  "country": "ZM",
  "phoneNo": "+260971234567",
  "requirements": [
    {
      "type": "DOCUMENT_SCAN"
    },
    {
      "type": "FACE_SCAN"
    }
  ],
  "url": "https://app.pawapass.com/your-company/aB1cD2eF",
  "status": "CREATED",
  "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",
  "identityDocument": {
    "type": "NATIONAL_ID",
    "country": "ZM",
    "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",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "faceScan": {
    "ageEstimation": "OVER_18",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "reviewResult": {
    "reason": "CAPTURE_ISSUE"
  },
  "createdBy": "[email protected]",
  "expiresAt": "2025-08-27T09:00:00.000Z",
  "createdAt": "2025-08-20T09:00:00.000Z",
  "updatedAt": "2025-08-20T09:00:00.000Z"
}

Authorizations

​
Authorization
string
header
required

Bearer token for authentication. See Authentication.

Body

application/json
​
externalId
string<no-null-bytes>
required

Your unique identifier for this user/verification

Minimum string length: 1
Example:

"user-zm-98765"

​
requirements
object[]
required

Array of verification requirements. See Requirements for workflow examples.

Minimum array length: 1
Example:
[
  { "type": "DOCUMENT_SCAN" },
  { "type": "FACE_SCAN" }
]
​
successUrl
string<uri>
required

URL to redirect user after successful verification completion

Pattern: ^https?://
Example:

"https://your-website.com/success"

​
errorUrl
string<uri>
required

URL to redirect user if verification fails or encounters an error

Pattern: ^https?://
Example:

"https://your-website.com/error"

​
supportUrl
string<uri>
required

URL where user can get support or help during verification

Pattern: ^https?://
Example:

"https://your-website.com/support"

​
country
enum<string>

ISO country code. See Supported countries for valid codes.

Available options:
AO,
BJ,
CM,
CD,
CG,
GH,
KE,
LS,
LR,
MW,
ML,
MZ,
NG,
RW,
SL,
TZ,
TG,
UG,
ZM
Example:

"ZM"

​
phoneNo
string<no-null-bytes>

Optional phone number. If not provided, extracted from metadata.

Example:

"+260971234567"

​
metadata
object

Custom key-value data to associate with the verification. Stored and returned in responses and webhooks.

Example:
{
  "reason": "kyc-onboarding",
  "channel": "mobile-app",
  "department": "compliance"
}
​
expiresAt
string<date-time>

Optional expiration date for this verification session (ISO 8601 format)

Example:

"2025-08-27T09:00:00.000Z"

​
createdBy
string<no-null-bytes>

Optional email/identifier of the person creating this verification

Example:

"[email protected]"

Response

Default Response

​
id
string
required

Verification ID

Example:

"aB1cD2eF"

​
externalId
string
required

Your external identifier for this verification

Example:

"user-zm-98765"

​
country
enum<string> | null
required

ISO country code associated with this verification

Available options:
AO,
BJ,
CM,
CD,
CG,
GH,
KE,
LS,
LR,
MW,
ML,
MZ,
NG,
RW,
SL,
TZ,
TG,
UG,
ZM
Example:

"ZM"

​
phoneNo
string | null
required

Phone number associated with this verification

Example:

"+260971234567"

​
requirements
object[]
required

Verification steps the user must complete. See Requirements for workflow examples.

Example:
[
  { "type": "DOCUMENT_SCAN" },
  { "type": "FACE_SCAN" }
]
​
url
string
required

URL where the user should complete the verification

Example:

"https://app.pawapass.com/your-company/aB1cD2eF"

​
status
enum<string>
required

Current status. See Verification flow for lifecycle.

Available options:
CREATED,
STARTED,
EXPIRED,
USER_DATA_COLLECTED,
REVIEW,
APPROVED,
DECLINED
Example:

"CREATED"

​
metadata
any | null
required

Custom metadata provided during verification creation

Example:
{
  "reason": "kyc-onboarding",
  "channel": "mobile-app",
  "department": "compliance"
}
​
successUrl
string
required

URL to redirect user after successful verification

Example:

"https://your-website.com/success"

​
errorUrl
string
required

URL to redirect user if verification fails

Example:

"https://your-website.com/error"

​
supportUrl
string
required

URL where user can get support

Example:

"https://your-website.com/support"

​
identityDocument
object
required

Extracted identity document data. Null if not yet available

​
faceScan
object
required

Face scan results. Null if not yet available

​
reviewResult
object
required

Review outcome details. Null when verification has not been reviewed or no review reason is available.

​
createdBy
string | null
required

Identifier of the person/system that created the verification

Example:

"[email protected]"

​
expiresAt
string<date-time>
required

Expiration date of the verification session

Example:

"2025-08-27T09:00:00.000Z"

​
createdAt
string<date-time>
required

Creation date of the verification

Example:

"2025-08-20T09:00:00.000Z"

​
updatedAt
string<date-time>
required

Date of the last update

Example:

"2025-08-20T09:00:00.000Z"