{"openapi":"3.1.0","info":{"title":"pawaPass API","version":"1.0.0"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token for authentication. See [Authentication](/authentication)."}},"schemas":{"ValidationReasonCode":{"type":"string","enum":["REQUIRED","INVALID_TYPE","INVALID_FORMAT","TOO_SHORT","TOO_LONG","TOO_SMALL","TOO_LARGE","TOO_FEW_ITEMS","TOO_MANY_ITEMS","NOT_IN_ENUM","NOT_EQUAL","NOT_UNIQUE","INVALID_PATTERN","UNEXPECTED_PROPERTY","NOT_SORTABLE","INVALID"],"description":"Machine-readable validation reason; the client maps this to localized copy."}}},"paths":{"/verifications/":{"post":{"operationId":"createVerification","tags":["verification"],"description":"Create a verification. If an active verification already exists for the same externalId, the existing one is returned with 200 OK and no new verification is created.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["externalId","country","successUrl","errorUrl","supportUrl"],"properties":{"externalId":{"type":"string","minLength":1,"format":"no-null-bytes","description":"Your unique identifier for this user/verification","example":"user-zm-98765"},"country":{"enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","CV","KH","CM","CA","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"],"description":"ISO country code. See [Supported countries](/supported-countries) for valid codes.","example":"ZM"},"phoneNo":{"type":"string","format":"no-null-bytes","description":"Optional phone number. If not provided, extracted from metadata.","example":"+260971234567"},"requirements":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["FACE_SCAN","DOCUMENT_SCAN"],"description":"Type of verification requirement (DOCUMENT_SCAN, FACE_SCAN, etc.)"},"options":{"type":"object","properties":{"previousVerificationId":{"type":"string","description":"ID of a past approved verification to match against (face-only re-verification)","example":"aB1cD2eF"}},"additionalProperties":{},"description":"Optional configuration for this requirement"}}},"minItems":1,"deprecated":true,"description":"Deprecated: configure a workflow in backoffice and select it with workflowId (or the country default) instead. Sending this is still accepted but does not decide the steps that run; when present it must be consistent with the resolved workflow. See [Requirements](/requirements).","example":[{"type":"DOCUMENT_SCAN"},{"type":"FACE_SCAN"}]},"metadata":{"type":"object","description":"Custom key-value data to associate with the verification. Stored and returned in responses and webhooks.","additionalProperties":{},"example":{"reason":"kyc-onboarding","channel":"mobile-app","department":"compliance"}},"successUrl":{"type":"string","format":"uri","pattern":"^https?://","description":"URL to redirect user after successful verification completion","example":"https://your-website.com/success"},"errorUrl":{"type":"string","format":"uri","pattern":"^https?://","description":"URL to redirect user if verification fails or encounters an error","example":"https://your-website.com/error"},"supportUrl":{"type":"string","format":"uri","pattern":"^https?://","description":"URL where user can get support or help during verification","example":"https://your-website.com/support"},"expiresAt":{"type":"string","format":"date-time","description":"Optional expiration date for this verification session (ISO 8601 format)","example":"2025-08-27T09:00:00.000Z"},"createdBy":{"type":"string","format":"no-null-bytes","description":"Optional email/identifier of the person creating this verification","example":"admin@your-company.com"},"workflowId":{"anyOf":[{"type":"string","format":"no-null-bytes","minLength":8,"maxLength":8,"examples":["aB1cD2eF"]},{"type":"null"}],"description":"Override the country-based workflow selection with a specific verification workflow. This is the 8-character workflow shortId shown in backoffice. Omit or send null to use the country default in force when the verification starts."}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["id","externalId","country","phoneNo","workflowId","requirements","url","status","metadata","successUrl","errorUrl","supportUrl","identityDocument","faceScan","reviewResult","createdBy","expiresAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Verification ID","example":"aB1cD2eF"},"externalId":{"type":"string","description":"Your external identifier for this verification","example":"user-zm-98765"},"country":{"anyOf":[{"enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","CV","KH","CM","CA","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"]},{"type":"null"}],"description":"ISO country code associated with this verification","example":"ZM"},"phoneNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone number associated with this verification","example":"+260971234567"},"workflowId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"shortId of the workflow that runs this verification. Null until the workflow is pinned: verifications that rely on the country default are pinned when they start, so this is null while they are still unstarted. Also null for legacy verifications created before workflows were persisted.","example":"wf3kD9aB"},"requirements":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["FACE_SCAN","DOCUMENT_SCAN"]},"options":{"type":"object","additionalProperties":{}}}},"description":"Verification steps the user must complete. See [Requirements](/requirements) for workflow examples.","example":[{"type":"DOCUMENT_SCAN"},{"type":"FACE_SCAN"}]},"url":{"type":"string","description":"URL where the user should complete the verification","example":"https://app.pawapass.com/your-company/aB1cD2eF"},"status":{"type":"string","enum":["CREATED","STARTED","EXPIRED","USER_DATA_COLLECTED","REVIEW","APPROVED","DECLINED"],"description":"Current status. See [Verification flow](/verification-flow) for lifecycle.","example":"CREATED"},"metadata":{"anyOf":[{},{"type":"null"}],"description":"Custom metadata provided during verification creation","example":{"reason":"kyc-onboarding","channel":"mobile-app","department":"compliance"}},"successUrl":{"type":"string","description":"URL to redirect user after successful verification","example":"https://your-website.com/success"},"errorUrl":{"type":"string","description":"URL to redirect user if verification fails","example":"https://your-website.com/error"},"supportUrl":{"type":"string","description":"URL where user can get support","example":"https://your-website.com/support"},"identityDocument":{"anyOf":[{"type":"object","required":["type","country","serialNo","nationalNo","firstName","lastName","dateOfBirth","placeOfBirth","nationality","expiryAt","issuedAt","issuingAuthority","placeOfIssue"],"properties":{"type":{"anyOf":[{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVER_LICENSE","REFUGEE_ID","VOTER_ID","RESIDENCE_PERMIT"]},{"type":"null"}],"description":"The type of the identity document","examples":["NATIONAL_ID"]},"country":{"anyOf":[{"enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","CV","KH","CM","CA","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"]},{"type":"null"}],"description":"The ISO code of the country that issued the document","examples":["ZM"]},"serialNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The serial number of the identity document","examples":["9876543/21/1"]},"nationalNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The national identification number","examples":["Z12345678"]},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The first name as extracted from the document","examples":["Tisa"]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The last name as extracted from the document","examples":["Banda"]},"dateOfBirth":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The date of birth in YYYY-MM-DD format","examples":["1997-05-10"]},"placeOfBirth":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The place of birth as listed on the document","examples":["Lusaka"]},"nationality":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The nationality as listed on the document","examples":["ZM"]},"expiryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The expiration date of the document in YYYY-MM-DD format","examples":["2032-05-09"]},"issuedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The date the document was issued in YYYY-MM-DD format","examples":["2022-05-10"]},"issuingAuthority":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The authority that issued the document","examples":["Republic of Zambia"]},"placeOfIssue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The location where the document was issued","examples":["Lusaka"]},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the document data"},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update to the document data"}}},{"type":"null"}],"description":"Extracted identity document data. Null if not yet available"},"faceScan":{"anyOf":[{"type":"object","required":["ageEstimation","createdAt","updatedAt"],"properties":{"ageEstimation":{"anyOf":[{"type":"string","enum":["UNKNOWN","UNDER_8","OVER_8","OVER_13","OVER_16","OVER_18","OVER_21","OVER_25","OVER_30"]},{"type":"null"}],"description":"Estimated age range from face scan","examples":["OVER_18"]},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the face scan data","examples":["2025-08-20T09:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update to the face scan data","examples":["2025-08-20T09:00:00.000Z"]}}},{"type":"null"}],"description":"Face scan results. Null if not yet available"},"reviewResult":{"anyOf":[{"type":"object","required":["category","reason","sensitive"],"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decline reason category code","examples":["CAPTURE_ISSUE","DOCUMENT_VALIDITY_CONCERN"]},"reason":{"type":"string","description":"Decline reason code","examples":["ONE_SIDE_MISSING","DOCUMENT_FAKE"]},"sensitive":{"type":"boolean","description":"Whether the underlying decline reason is flagged sensitive. Partner UIs may suppress reason detail when true."}}},{"type":"null"}],"description":"Review outcome details. Null when verification has not been reviewed or no review reason is available."},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the person/system that created the verification","example":"admin@your-company.com"},"expiresAt":{"type":"string","format":"date-time","description":"Expiration date of the verification session","example":"2025-08-27T09:00:00.000Z"},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the verification","example":"2025-08-20T09:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update","example":"2025-08-20T09:00:00.000Z"}}}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["id","externalId","country","phoneNo","workflowId","requirements","url","status","metadata","successUrl","errorUrl","supportUrl","identityDocument","faceScan","reviewResult","createdBy","expiresAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Verification ID","example":"aB1cD2eF"},"externalId":{"type":"string","description":"Your external identifier for this verification","example":"user-zm-98765"},"country":{"anyOf":[{"enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","CV","KH","CM","CA","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"]},{"type":"null"}],"description":"ISO country code associated with this verification","example":"ZM"},"phoneNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone number associated with this verification","example":"+260971234567"},"workflowId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"shortId of the workflow that runs this verification. Null until the workflow is pinned: verifications that rely on the country default are pinned when they start, so this is null while they are still unstarted. Also null for legacy verifications created before workflows were persisted.","example":"wf3kD9aB"},"requirements":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["FACE_SCAN","DOCUMENT_SCAN"]},"options":{"type":"object","additionalProperties":{}}}},"description":"Verification steps the user must complete. See [Requirements](/requirements) for workflow examples.","example":[{"type":"DOCUMENT_SCAN"},{"type":"FACE_SCAN"}]},"url":{"type":"string","description":"URL where the user should complete the verification","example":"https://app.pawapass.com/your-company/aB1cD2eF"},"status":{"type":"string","enum":["CREATED","STARTED","EXPIRED","USER_DATA_COLLECTED","REVIEW","APPROVED","DECLINED"],"description":"Current status. See [Verification flow](/verification-flow) for lifecycle.","example":"CREATED"},"metadata":{"anyOf":[{},{"type":"null"}],"description":"Custom metadata provided during verification creation","example":{"reason":"kyc-onboarding","channel":"mobile-app","department":"compliance"}},"successUrl":{"type":"string","description":"URL to redirect user after successful verification","example":"https://your-website.com/success"},"errorUrl":{"type":"string","description":"URL to redirect user if verification fails","example":"https://your-website.com/error"},"supportUrl":{"type":"string","description":"URL where user can get support","example":"https://your-website.com/support"},"identityDocument":{"anyOf":[{"type":"object","required":["type","country","serialNo","nationalNo","firstName","lastName","dateOfBirth","placeOfBirth","nationality","expiryAt","issuedAt","issuingAuthority","placeOfIssue"],"properties":{"type":{"anyOf":[{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVER_LICENSE","REFUGEE_ID","VOTER_ID","RESIDENCE_PERMIT"]},{"type":"null"}],"description":"The type of the identity document","examples":["NATIONAL_ID"]},"country":{"anyOf":[{"enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","CV","KH","CM","CA","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"]},{"type":"null"}],"description":"The ISO code of the country that issued the document","examples":["ZM"]},"serialNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The serial number of the identity document","examples":["9876543/21/1"]},"nationalNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The national identification number","examples":["Z12345678"]},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The first name as extracted from the document","examples":["Tisa"]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The last name as extracted from the document","examples":["Banda"]},"dateOfBirth":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The date of birth in YYYY-MM-DD format","examples":["1997-05-10"]},"placeOfBirth":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The place of birth as listed on the document","examples":["Lusaka"]},"nationality":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The nationality as listed on the document","examples":["ZM"]},"expiryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The expiration date of the document in YYYY-MM-DD format","examples":["2032-05-09"]},"issuedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The date the document was issued in YYYY-MM-DD format","examples":["2022-05-10"]},"issuingAuthority":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The authority that issued the document","examples":["Republic of Zambia"]},"placeOfIssue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The location where the document was issued","examples":["Lusaka"]},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the document data"},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update to the document data"}}},{"type":"null"}],"description":"Extracted identity document data. Null if not yet available"},"faceScan":{"anyOf":[{"type":"object","required":["ageEstimation","createdAt","updatedAt"],"properties":{"ageEstimation":{"anyOf":[{"type":"string","enum":["UNKNOWN","UNDER_8","OVER_8","OVER_13","OVER_16","OVER_18","OVER_21","OVER_25","OVER_30"]},{"type":"null"}],"description":"Estimated age range from face scan","examples":["OVER_18"]},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the face scan data","examples":["2025-08-20T09:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update to the face scan data","examples":["2025-08-20T09:00:00.000Z"]}}},{"type":"null"}],"description":"Face scan results. Null if not yet available"},"reviewResult":{"anyOf":[{"type":"object","required":["category","reason","sensitive"],"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decline reason category code","examples":["CAPTURE_ISSUE","DOCUMENT_VALIDITY_CONCERN"]},"reason":{"type":"string","description":"Decline reason code","examples":["ONE_SIDE_MISSING","DOCUMENT_FAKE"]},"sensitive":{"type":"boolean","description":"Whether the underlying decline reason is flagged sensitive. Partner UIs may suppress reason detail when true."}}},{"type":"null"}],"description":"Review outcome details. Null when verification has not been reviewed or no review reason is available."},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the person/system that created the verification","example":"admin@your-company.com"},"expiresAt":{"type":"string","format":"date-time","description":"Expiration date of the verification session","example":"2025-08-27T09:00:00.000Z"},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the verification","example":"2025-08-20T09:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update","example":"2025-08-20T09:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["statusCode","code","message"],"properties":{"statusCode":{"type":"number","enum":[400]},"code":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Input data is invalid. Please check the details."},"details":{"type":"array","items":{"type":"object","required":["field","reasonCode"],"properties":{"field":{"type":"string","description":"Dot-path of the offending field, e.g. 'address.city'."},"reasonCode":{"$ref":"#/components/schemas/ValidationReasonCode"},"params":{"type":"object","description":"Interpolation data for the reason, e.g. { limit: 5 } or { allowed: [...] }.","additionalProperties":{}}}},"description":"Structured, localizable field-validation reasons."}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["statusCode","code","message"],"properties":{"statusCode":{"type":"number","enum":[401]},"code":{"type":"string","description":"Error code","example":"UNAUTHORIZED_ERROR"},"message":{"type":"string","description":"Error message","example":"Unauthorized"}}}}}}}},"get":{"operationId":"listVerifications","tags":["verification"],"parameters":[{"schema":{"type":"number","minimum":0,"default":0},"in":"query","name":"page","required":false,"description":"The page number to retrieve"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":15},"in":"query","name":"limit","required":false,"description":"The number of items to return per page"},{"schema":{"type":"string"},"example":"aB1cD2eF","in":"query","name":"id","required":false,"description":"Filter by verification ID"},{"schema":{"type":"string"},"example":"user-zm-98765","in":"query","name":"externalId","required":false,"description":"Filter by your external ID"},{"schema":{"type":"array","items":{"type":"string","enum":["CREATED","STARTED","EXPIRED","USER_DATA_COLLECTED","REVIEW","APPROVED","DECLINED"]}},"example":["APPROVED","DECLINED"],"in":"query","name":"statuses","required":false,"description":"Filter by status. Supports multiple values (e.g., ?statuses=APPROVED&statuses=DECLINED)"},{"schema":{"type":"string","format":"date-time"},"example":"2025-01-01T00:00:00.000Z","in":"query","name":"fromCreatedAt","required":false,"description":"Filter verifications created from this date (inclusive). Format ISO 8601"},{"schema":{"type":"string","format":"date-time"},"example":"2025-12-31T23:59:59.000Z","in":"query","name":"toCreatedAt","required":false,"description":"Filter verifications created up to this date (inclusive). Format ISO 8601"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["items","count"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","externalId","country","phoneNo","workflowId","requirements","url","status","metadata","successUrl","errorUrl","supportUrl","identityDocument","faceScan","reviewResult","createdBy","expiresAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Verification ID","example":"aB1cD2eF"},"externalId":{"type":"string","description":"Your external identifier for this verification","example":"user-zm-98765"},"country":{"anyOf":[{"enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","CV","KH","CM","CA","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"]},{"type":"null"}],"description":"ISO country code associated with this verification","example":"ZM"},"phoneNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone number associated with this verification","example":"+260971234567"},"workflowId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"shortId of the workflow that runs this verification. Null until the workflow is pinned: verifications that rely on the country default are pinned when they start, so this is null while they are still unstarted. Also null for legacy verifications created before workflows were persisted.","example":"wf3kD9aB"},"requirements":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["FACE_SCAN","DOCUMENT_SCAN"]},"options":{"type":"object","additionalProperties":{}}}},"description":"Verification steps the user must complete. See [Requirements](/requirements) for workflow examples.","example":[{"type":"DOCUMENT_SCAN"},{"type":"FACE_SCAN"}]},"url":{"type":"string","description":"URL where the user should complete the verification","example":"https://app.pawapass.com/your-company/aB1cD2eF"},"status":{"type":"string","enum":["CREATED","STARTED","EXPIRED","USER_DATA_COLLECTED","REVIEW","APPROVED","DECLINED"],"description":"Current status. See [Verification flow](/verification-flow) for lifecycle.","example":"CREATED"},"metadata":{"anyOf":[{},{"type":"null"}],"description":"Custom metadata provided during verification creation","example":{"reason":"kyc-onboarding","channel":"mobile-app","department":"compliance"}},"successUrl":{"type":"string","description":"URL to redirect user after successful verification","example":"https://your-website.com/success"},"errorUrl":{"type":"string","description":"URL to redirect user if verification fails","example":"https://your-website.com/error"},"supportUrl":{"type":"string","description":"URL where user can get support","example":"https://your-website.com/support"},"identityDocument":{"anyOf":[{"type":"object","required":["type","country","serialNo","nationalNo","firstName","lastName","dateOfBirth","placeOfBirth","nationality","expiryAt","issuedAt","issuingAuthority","placeOfIssue"],"properties":{"type":{"anyOf":[{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVER_LICENSE","REFUGEE_ID","VOTER_ID","RESIDENCE_PERMIT"]},{"type":"null"}],"description":"The type of the identity document","examples":["NATIONAL_ID"]},"country":{"anyOf":[{"enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","CV","KH","CM","CA","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"]},{"type":"null"}],"description":"The ISO code of the country that issued the document","examples":["ZM"]},"serialNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The serial number of the identity document","examples":["9876543/21/1"]},"nationalNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The national identification number","examples":["Z12345678"]},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The first name as extracted from the document","examples":["Tisa"]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The last name as extracted from the document","examples":["Banda"]},"dateOfBirth":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The date of birth in YYYY-MM-DD format","examples":["1997-05-10"]},"placeOfBirth":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The place of birth as listed on the document","examples":["Lusaka"]},"nationality":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The nationality as listed on the document","examples":["ZM"]},"expiryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The expiration date of the document in YYYY-MM-DD format","examples":["2032-05-09"]},"issuedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The date the document was issued in YYYY-MM-DD format","examples":["2022-05-10"]},"issuingAuthority":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The authority that issued the document","examples":["Republic of Zambia"]},"placeOfIssue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The location where the document was issued","examples":["Lusaka"]},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the document data"},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update to the document data"}}},{"type":"null"}],"description":"Extracted identity document data. Null if not yet available"},"faceScan":{"anyOf":[{"type":"object","required":["ageEstimation","createdAt","updatedAt"],"properties":{"ageEstimation":{"anyOf":[{"type":"string","enum":["UNKNOWN","UNDER_8","OVER_8","OVER_13","OVER_16","OVER_18","OVER_21","OVER_25","OVER_30"]},{"type":"null"}],"description":"Estimated age range from face scan","examples":["OVER_18"]},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the face scan data","examples":["2025-08-20T09:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update to the face scan data","examples":["2025-08-20T09:00:00.000Z"]}}},{"type":"null"}],"description":"Face scan results. Null if not yet available"},"reviewResult":{"anyOf":[{"type":"object","required":["category","reason","sensitive"],"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decline reason category code","examples":["CAPTURE_ISSUE","DOCUMENT_VALIDITY_CONCERN"]},"reason":{"type":"string","description":"Decline reason code","examples":["ONE_SIDE_MISSING","DOCUMENT_FAKE"]},"sensitive":{"type":"boolean","description":"Whether the underlying decline reason is flagged sensitive. Partner UIs may suppress reason detail when true."}}},{"type":"null"}],"description":"Review outcome details. Null when verification has not been reviewed or no review reason is available."},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the person/system that created the verification","example":"admin@your-company.com"},"expiresAt":{"type":"string","format":"date-time","description":"Expiration date of the verification session","example":"2025-08-27T09:00:00.000Z"},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the verification","example":"2025-08-20T09:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update","example":"2025-08-20T09:00:00.000Z"}}}},"count":{"type":"number","description":"The total number of items matching the filters"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["statusCode","code","message"],"properties":{"statusCode":{"type":"number","enum":[400]},"code":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Input data is invalid. Please check the details."},"details":{"type":"array","items":{"type":"object","required":["field","reasonCode"],"properties":{"field":{"type":"string","description":"Dot-path of the offending field, e.g. 'address.city'."},"reasonCode":{"$ref":"#/components/schemas/ValidationReasonCode"},"params":{"type":"object","description":"Interpolation data for the reason, e.g. { limit: 5 } or { allowed: [...] }.","additionalProperties":{}}}},"description":"Structured, localizable field-validation reasons."}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["statusCode","code","message"],"properties":{"statusCode":{"type":"number","enum":[401]},"code":{"type":"string","description":"Error code","example":"UNAUTHORIZED_ERROR"},"message":{"type":"string","description":"Error message","example":"Unauthorized"}}}}}}}}},"/verifications/{id}":{"get":{"operationId":"getVerification","tags":["verification"],"parameters":[{"schema":{"type":"string"},"example":"aB1cD2eF","in":"path","name":"id","required":true,"description":"The verification ID"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["id","externalId","country","phoneNo","workflowId","requirements","url","status","metadata","successUrl","errorUrl","supportUrl","identityDocument","faceScan","reviewResult","createdBy","expiresAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Verification ID","example":"aB1cD2eF"},"externalId":{"type":"string","description":"Your external identifier for this verification","example":"user-zm-98765"},"country":{"anyOf":[{"enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","CV","KH","CM","CA","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"]},{"type":"null"}],"description":"ISO country code associated with this verification","example":"ZM"},"phoneNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Phone number associated with this verification","example":"+260971234567"},"workflowId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"shortId of the workflow that runs this verification. Null until the workflow is pinned: verifications that rely on the country default are pinned when they start, so this is null while they are still unstarted. Also null for legacy verifications created before workflows were persisted.","example":"wf3kD9aB"},"requirements":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["FACE_SCAN","DOCUMENT_SCAN"]},"options":{"type":"object","additionalProperties":{}}}},"description":"Verification steps the user must complete. See [Requirements](/requirements) for workflow examples.","example":[{"type":"DOCUMENT_SCAN"},{"type":"FACE_SCAN"}]},"url":{"type":"string","description":"URL where the user should complete the verification","example":"https://app.pawapass.com/your-company/aB1cD2eF"},"status":{"type":"string","enum":["CREATED","STARTED","EXPIRED","USER_DATA_COLLECTED","REVIEW","APPROVED","DECLINED"],"description":"Current status. See [Verification flow](/verification-flow) for lifecycle.","example":"CREATED"},"metadata":{"anyOf":[{},{"type":"null"}],"description":"Custom metadata provided during verification creation","example":{"reason":"kyc-onboarding","channel":"mobile-app","department":"compliance"}},"successUrl":{"type":"string","description":"URL to redirect user after successful verification","example":"https://your-website.com/success"},"errorUrl":{"type":"string","description":"URL to redirect user if verification fails","example":"https://your-website.com/error"},"supportUrl":{"type":"string","description":"URL where user can get support","example":"https://your-website.com/support"},"identityDocument":{"anyOf":[{"type":"object","required":["type","country","serialNo","nationalNo","firstName","lastName","dateOfBirth","placeOfBirth","nationality","expiryAt","issuedAt","issuingAuthority","placeOfIssue"],"properties":{"type":{"anyOf":[{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVER_LICENSE","REFUGEE_ID","VOTER_ID","RESIDENCE_PERMIT"]},{"type":"null"}],"description":"The type of the identity document","examples":["NATIONAL_ID"]},"country":{"anyOf":[{"enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","CV","KH","CM","CA","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","SZ","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"]},{"type":"null"}],"description":"The ISO code of the country that issued the document","examples":["ZM"]},"serialNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The serial number of the identity document","examples":["9876543/21/1"]},"nationalNo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The national identification number","examples":["Z12345678"]},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The first name as extracted from the document","examples":["Tisa"]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The last name as extracted from the document","examples":["Banda"]},"dateOfBirth":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The date of birth in YYYY-MM-DD format","examples":["1997-05-10"]},"placeOfBirth":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The place of birth as listed on the document","examples":["Lusaka"]},"nationality":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The nationality as listed on the document","examples":["ZM"]},"expiryAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The expiration date of the document in YYYY-MM-DD format","examples":["2032-05-09"]},"issuedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The date the document was issued in YYYY-MM-DD format","examples":["2022-05-10"]},"issuingAuthority":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The authority that issued the document","examples":["Republic of Zambia"]},"placeOfIssue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The location where the document was issued","examples":["Lusaka"]},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the document data"},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update to the document data"}}},{"type":"null"}],"description":"Extracted identity document data. Null if not yet available"},"faceScan":{"anyOf":[{"type":"object","required":["ageEstimation","createdAt","updatedAt"],"properties":{"ageEstimation":{"anyOf":[{"type":"string","enum":["UNKNOWN","UNDER_8","OVER_8","OVER_13","OVER_16","OVER_18","OVER_21","OVER_25","OVER_30"]},{"type":"null"}],"description":"Estimated age range from face scan","examples":["OVER_18"]},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the face scan data","examples":["2025-08-20T09:00:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update to the face scan data","examples":["2025-08-20T09:00:00.000Z"]}}},{"type":"null"}],"description":"Face scan results. Null if not yet available"},"reviewResult":{"anyOf":[{"type":"object","required":["category","reason","sensitive"],"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Decline reason category code","examples":["CAPTURE_ISSUE","DOCUMENT_VALIDITY_CONCERN"]},"reason":{"type":"string","description":"Decline reason code","examples":["ONE_SIDE_MISSING","DOCUMENT_FAKE"]},"sensitive":{"type":"boolean","description":"Whether the underlying decline reason is flagged sensitive. Partner UIs may suppress reason detail when true."}}},{"type":"null"}],"description":"Review outcome details. Null when verification has not been reviewed or no review reason is available."},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the person/system that created the verification","example":"admin@your-company.com"},"expiresAt":{"type":"string","format":"date-time","description":"Expiration date of the verification session","example":"2025-08-27T09:00:00.000Z"},"createdAt":{"type":"string","format":"date-time","description":"Creation date of the verification","example":"2025-08-20T09:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update","example":"2025-08-20T09:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["statusCode","code","message"],"properties":{"statusCode":{"type":"number","enum":[400]},"code":{"type":"string","description":"Error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Input data is invalid. Please check the details."},"details":{"type":"array","items":{"type":"object","required":["field","reasonCode"],"properties":{"field":{"type":"string","description":"Dot-path of the offending field, e.g. 'address.city'."},"reasonCode":{"$ref":"#/components/schemas/ValidationReasonCode"},"params":{"type":"object","description":"Interpolation data for the reason, e.g. { limit: 5 } or { allowed: [...] }.","additionalProperties":{}}}},"description":"Structured, localizable field-validation reasons."}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["statusCode","code","message"],"properties":{"statusCode":{"type":"number","enum":[401]},"code":{"type":"string","description":"Error code","example":"UNAUTHORIZED_ERROR"},"message":{"type":"string","description":"Error message","example":"Unauthorized"}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["statusCode","code","message"],"properties":{"statusCode":{"type":"number","enum":[404]},"code":{"type":"string","description":"Error code","example":"NOT_FOUND_ERROR"},"message":{"type":"string","description":"Error message","example":"Not found"}}}}}}}}}},"servers":[{"url":"https://api.pawapass.com/v2","description":"Production"},{"url":"https://api-sandbox1.pawapass.com/v2","description":"Sandbox"}],"tags":[{"name":"verification"}]}