Skip to main content
POST
/
verifications
Create a new verification
curl --request POST \
  --url https://integration-api.dev.pawapass.com/verifications/ \
  --header 'Content-Type: application/json' \
  --header 'X-AUTH-KEY: <api-key>' \
  --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": {
    "phoneNumber": "+260971234567",
    "jurisdiction": "ZM",
    "reason": "kyc-onboarding"
  },
  "expiresAt": "2023-11-07T05:31:56Z",
  "createdBy": "[email protected]"
}
'
{
  "id": "aB1cD2eF",
  "externalId": "user-zm-98765",
  "requirements": [
    {
      "type": "DOCUMENT_SCAN"
    },
    {
      "type": "FACE_SCAN"
    }
  ],
  "url": "https://app.pawapass.com/your-company/aB1cD2eF",
  "status": "CREATED",
  "metadata": {
    "phoneNumber": "+260971234567",
    "jurisdiction": "ZM",
    "reason": "kyc-onboarding"
  },
  "successUrl": "https://your-website.com/success",
  "errorUrl": "https://your-website.com/error",
  "supportUrl": "https://your-website.com/support",
  "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",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "createdBy": "[email protected]",
  "expiresAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
X-AUTH-KEY
string
header
required

API key for partner 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 the user must complete

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

URL to redirect user after successful verification completion

Example:

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

​
errorUrl
string<uri>
required

URL to redirect user if verification fails or encounters an error

Example:

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

​
supportUrl
string<uri>
required

URL where user can get support or help during verification

Example:

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

​
country
enum<string>

Optional ISO country code

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:
{
  "phoneNumber": "+260971234567",
  "jurisdiction": "ZM",
  "reason": "kyc-onboarding"
}
​
expiresAt
string<date-time>

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

​
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"

​
requirements
object[]
required

Verification steps the user must complete

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 of the verification

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

"CREATED"

​
metadata
any | null
required

Custom metadata provided during verification creation

Example:
{
  "phoneNumber": "+260971234567",
  "jurisdiction": "ZM",
  "reason": "kyc-onboarding"
}
​
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

​
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

​
createdAt
string<date-time>
required

Creation date of the verification

​
updatedAt
string<date-time>
required

Date of the last update