Document Verification

Document verification checks the authenticity of a passport, driver's license, or national identity card from an uploaded document image. The verification is asynchronous: the initial response returns a DV- reference with a processing status, and the completed result is delivered by webhook or retrieved with the Query Document Verification endpoint.

📘
NOTE: Always ensure that you have sufficient funds in your available balance and that document verification is enabled for the requested country.

Supported Countries and Document Types

Country	Country code	Supported type values	Returned identity type
Nigeria	ng	passport, drivers_license	ng_passport_doc, ng_drivers_license_doc
Ghana	gh	passport, drivers_license, national_id	gh_passport_doc, gh_drivers_license_doc, gh_national_id_doc
Kenya	ke	passport, national_id	ke_passport_doc, ke_national_id_doc
South Africa	za	passport	za_passport_doc
United States	us	passport, drivers_license	us_passport_doc, us_drivers_license_doc
Ivory Coast (Côte d'Ivoire)	ci	passport, national_id	ci_passport_doc, ci_national_id_doc
United Kingdom	gb	passport, drivers_license, national_id	gb_passport_doc, gb_drivers_license_doc, gb_national_id_doc
Egypt	eg	passport, drivers_license, national_id	eg_passport_doc, eg_drivers_license_doc, eg_national_id_doc

Verify a document

To initiate a document verification, make a POST request to:

POST https://api.korapay.com/merchant/api/v1/identities/verifications/documents

Authenticate the request using your Kora secret key.

Request header

idempotency-key:

Optional. Supply a unique value to make retries idempotent. Reuse the same key only when retrying the same request; use a new key for a different verification.

Request parameters

Field	Data type	Description
id	string	Required. Document number or identifier, 3–64 characters.
country	string	Required. Supported ISO alpha-2 country code shown in the table above.
type	string	Required. passport, drivers_license, or national_id, where supported for the country.
document_front	string	Required. A public HTTPS image URL or a Base64-encoded JPEG/PNG image supplied as a data URI, for example, data:image/jpeg;base64,...
document_back	string	Required for a two-sided document; otherwise optional. Accepts a public HTTPS image URL or a Base64-encoded JPEG/PNG image supplied as a data URI.
first_name	string	Optional. First name to compare with extracted document data.
last_name	string	Optional. Last name to compare with extracted document data.
date_of_birth	string	Optional. Date of birth to compare, in YYYY-MM-DD format.
phone	string	Optional. Phone number with country code, beginning with +.
verification_consent	Boolean	Required. Indicates that the subject has given consent. Must be true.
requester	object	Optional. { "first_name": "...", "last_name": "..." }.

Passport request example

{
  "id": "A48261903",
  "country": "ng",
  "type": "passport",
  "document_front": "data:image/jpeg;base64,<BASE64_OF_nigeria-passport-biodata-test.jpg>",
  "first_name": "Adeyemi Chukwuma",
  "last_name": "Okoro",
  "date_of_birth": "1990-06-15",
  "verification_consent": true,
  "requester": {
    "first_name": "API",
    "last_name": "User"
  }
}

Two-sided document request example

{
  "id": "GHA-482619031-5",
  "country": "gh",
  "type": "national_id",
  "document_front": "https://merchant.example.com/ghana-national-id-front-test.jpg",
  "document_back": "https://merchant.example.com/ghana-national-id-back-test.jpg",
  "verification_consent": true
}

Both document_front and document_back accept either a public HTTPS image URL or a Base64-encoded image data URI. When using Base64, prepend the correct data URI prefix, such as data:image/jpeg;base64,.

Initial response

{
  "status": true,
  "message": "Document verification initiated successfully",
  "data": {
    "reference": "DV-abc123xyz",
    "id": "A48261903",
    "id_type": "ng_passport_doc",
    "country": "ng",
    "document_type": "passport",
    "verification_type": "kyc",
    "status": "processing",
    "requested_by": "API User"
  }
}

Completed verification

Completion is reported through the identity.document_verification webhook. A completed verification can have an authenticity status of authentic, suspicious, tampered, or failed.

Webhook notification example

{
  "event": "identity.document_verification.completed",
  "data": {
    "reference": "DV-abc123xyz",
    "identity_type": "ng_passport_doc",
    "status": "authentic",
    "validation_result": "valid",
    "date": "2026-08-30T12:00:00.000Z"
  }
}

Query Document Verification

Retrieve a document verification using the DV- reference returned by the initial request. The response includes the available request data, extracted document data, validation results, and uploaded document URLs.

Sample request (GET)

https://api.korapay.com/merchant/api/v1/identities/verifications/documents/DV-abc123xyz

Sample response

{
  "status": true,
  "message": "Document verification retrieved successfully",
  "data": {
    "reference": "DV-abc123xyz",
    "id": "A48261903",
    "full_name": "Adeyemi Chukwuma Okoro",
    "masked_id": "******903",
    "country": "ng",
    "type": "passport",
    "verification_type": "kyc",
    "class": "document_verification",
    "identity_type": "ng_passport_doc",
    "requested_by": "API User",
    "status": "authentic",
    "validation": {
      "document_number": { "value": "A48261903", "match": true },
      "country": { "value": "ng", "match": true },
      "document_type": { "value": "passport", "match": true },
      "first_name": { "value": "Adeyemi Chukwuma", "match": true },
      "last_name": { "value": "Okoro", "match": true },
      "date_of_birth": { "value": "1990-06-15", "match": true }
    },
    "date_created": "2026-08-30T11:59:55.000Z",
    "input": {
      "document_number": "A48261903",
      "country": "ng",
      "document_type": "passport",
      "first_name": "Adeyemi Chukwuma",
      "last_name": "Okoro",
      "date_of_birth": "1990-06-15"
    },
    "extracted": {
      "document_number": "A48261903",
      "country": "ng",
      "document_type": "passport",
      "first_name": "Adeyemi Chukwuma",
      "last_name": "Okoro",
      "gender": "male",
      "date_of_birth": "1990-06-15",
      "authenticity_status": "authentic"
    },
    "document_front": "https://example.com/document-front.jpg"
  }
}

List Document Verifications

Retrieve document verifications using pagination and optional filters. Supported filters include reference, status, verification type (type), identity type (identityType), country, startDate, endDate, and keyword.

Sample request (GET)

https://api.korapay.com/merchant/api/v1/identities/verifications/documents?page=1&limit=10

Sample response

{
  "status": true,
  "message": "Document verifications retrieved successfully",
  "data": {
    "data": [
      {
        "reference": "DV-abc123xyz",
        "full_name": "Adeyemi Chukwuma Okoro",
        "masked_id": "******903",
        "country": "ng",
        "type": "passport",
        "verification_type": "kyc",
        "class": "document_verification",
        "identity_type": "ng_passport_doc",
        "requested_by": "API User",
        "status": "authentic",
        "date_created": "2026-08-30T11:59:55.000Z",
        "input": {
          "country": "ng",
          "document_type": "passport",
          "first_name": "Adeyemi Chukwuma",
          "last_name": "Okoro",
          "date_of_birth": "1990-06-15"
        }
      }
    ],
    "paging": {
      "total_items": 1,
      "page_size": 10,
      "current": 1,
      "count": 1
    },
    "links": [
      {
        "href": "https://api.korapay.com/merchant/api/v1/identities/verifications/documents?limit=10&page=1",
        "rel": "current",
        "method": "GET"
      }
    ]
  }
}