Verify Entity (KYC)

This endpoint allows you to run a KYC check on an entity, this can only be an individual.

POST {{baseurl}}/v2/api/entities/:entityId/identity

Headers

Name	Type	Description
token*	String	API secret token

Parameter

Field	Type	Description
entityId*	String	Id of the entity being checked.

Request Body

Field	Type	Description
entityType*	String	Type of entity being checked or verified. Allowed values: "individual"
isSubjectConsent*	Boolean	Consent of the individual or entity being verified. Allowed values: true
identity*	Object	Identity document data.
id	String	Unique identifier depending on the type (e.g., BVN, NIN, VNIN, Passport No., etc.).
countryCode*	String	Country code of the identity document (ISO 3166-1 alpha-2). Size range: 2
idType*	String	Document type code. Must be supported by the country.
mobile	String	Mobile number (used with nin_by_phone).
accountNumber	String	10-digit account number (used with BAV).
bankCode	String	Bank code for BAV verification.
lastName	String	Last name (used with passport verification).
shouldRetrivedNin	Boolean	Whether to fetch linked NIN from BVN. Default value: false
premiumBVN	Boolean	Enable premium BVN check. Default value: false
premiumNin	Boolean	Enable premium NIN check. Default value: false
fullDetails	Boolean	Request extended BVN profile. Default value: false
metadata	Object	Optional metadata for auditing, tracking, or extensions.
validations	Object	Validation payload for cross-checking identity.
data	Object	Personal info to validate.
firstName	String	First name to validate.
lastName	String	Last name to validate.
dateOfBirth	String	Date of birth to validate. Allowed values: "YYYY-MM-DD"
selfie	Object	Selfie validation block.
image	String	URL to a selfie image. Size range: URI
advanced	Boolean	For kenya_scrub - whether to run advanced check. [identity.bankId] Bank ID (Kenya).
bank	String	Bank name (South Africa).
bankBranchCode	String	Required in South African BAV.
accountType	String	Account type (e.g., "Savings", "Current") for ZA BAV. Default value: Savings
type	String	type (e.g., "old_voter_card", "new_voter_card") for GH voter ID.

Nigeria KYC

Verify Entity Sample Request (BVN)

{
    "entityType": "individual",
    "isSubjectConsent": true,
    "identity": {
        "id": "A11111111",
        "countryCode": "NG",
        "idType": "bvn",
        "premiumBVN": false
    }
}

Verify Entity Sample Request (NIN)

Verify Entity Sample Request (Advanced Phone Search)

Verify Entity Sample Request (Basic Phone Search)

Nigeria KYC (contd.)

Verify Entity Sample Request (BAV)

{
  "entityType": "individual",
  "isSubjectConsent": true,
  "identity": {
    "accountNumber": "014125xxxx",
       "bankCode": "058",
   }
 }

Verify Entity Sample Request (Passport)

Verify Entity Sample Request (Drivers License)

Verify Entity Sample Request (PVC)

Kenya KYC

Verify Entity Sample Request (Kenya Drivers License)

{
    "entityType": "individual",
    "isSubjectConsent": true,
    "identity": {
        "idType": "keDriversLicense",
        "countryCode": "KE",
        "id": "111111111"
    }
}

Verify Entity Sample Request (Kenya Alien ID)

Verify Entity Sample Request (Kenya National ID)

Verify Entity Sample Request (Kenya Passport)

Ghana KYC

Verify Entity Sample Request (Ghana New Voter ID)

{
    "entityType": "individual",
    "isSubjectConsent": true,
    "identity": {
        "idType": "ghVoter",
        "countryCode": "GH",
        "id": "G0000575",
        "type": "new_voter_card"
    }
}

Verify Entity Sample Request (Ghana Old Voter ID)

Verify Entity Sample Request (Ghana Passport)

South Africa KYC

Verify Entity Sample Request (South Africa ID)

{
    "entityType": "individual",
    "isSubjectConsent": true,
    "identity": {
        "idType": "zaSAID",
        "countryCode": "ZA",
        "id": "8012185201081"
    }
}

Success Response (New Business)

{
  "success": true,
  "status_code": 201,
  "message": "Business check successful!",
  "data": {
    "id": "69dab502682626b4e9e6d77c",
        "entity": {
            "entityId": "ent_69dab0119abad240d91071a4",
            "isNew": true,
            "message": "Entity created successfully."
        },
        "businessCheck": {
            "id": "69dab502682626b4e9e6d77c",
            "status": "found",
            "businessId": "69b3c7f1556f687f7fb8a5bd",
            "parentId": null,
            "isConsent": true,
            "type": "basic_company_check",
            "searchTerm": "RC00000000",
            "name": "John Doe Inc",
            "registrationNumber": "RC00000000",
            "companyStatus": "ACTIVE",
            "requestedAt": "2026-04-11T20:54:27.818Z",
            "country": "Nigeria",
            "createdAt": "2022-11-03T14:16:54.235Z",
            "lastModifiedAt": "2022-11-03T14:16:54.235Z",
            "typeOfEntity": "PRIVATE COMPANY LIMITED BY SHARES",
            "registrationDate": "2017-06-09",
            "natureOfBusiness": null,
            "amlReport": null,
            "adverseMediaReport": null,
            "requestedBy": {
                "firstName": "Jamal",
                "lastName": "Akinyelu",
                "middleName": "",
                "id": "69b3c7f6556f687f7fb8a5c7"
            }
        }
      },

Success Response (Existing Business)

Not Found

Error Response

{
  "success": false,
  "statusCode": 404,
  "message": "You have attempted to get a resource that does not exist.",
  "name": "ResourceNotFoundError",
  "data": {}
}