Verify Entity (KYB)

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

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

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: "business"
isSubjectConsent*	Boolean	Consent of the individual or entity being verified. Allowed values: true
checkType	String	Type of business check { basic, standard or premium }.
incorporationNumber	String	Business registration number.
incorporationCountry	String	Country code of business incorporation (ISO 3166-1 alpha-2). Size range: 2

Verify Entity Sample Request (Business)

{
  "entityType": "business",
  "isSubjectConsent": true,
  "incorporationNumber": "RC123456",
  "incorporationCountry": "NG",
  "checkType": "basic",
}

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)

{
  "success": true,
  "status_code": 200,
  "message": "Business check successful!",
  "data": {
     "id": "ent_69dab0119abad240d91071a4",
        "entity": {
            "entityId": "ent_69dab0119abad240d91071a4",
            "isNew": false
        },
        "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"
            }
        }
    },
  "links": []
}

Not Found

{
  "success": true,
  "status_code": 200,
  "message": "Business check successful!",
  "data": {
     "id": null,
        "entity": {},
        "businessCheck": {
            "id": "69dab502682626b4e9e6d77c",
            "status": "not_found",
            "businessId": "69b3c7f1556f687f7fb8a5bd",
            "parentId": null,
            "isConsent": true,
            "type": "basic_company_check",
            "searchTerm": "RC00000000",
            "name": "",
            "registrationNumber": "",
            "companyStatus": "",
            "requestedAt": "2026-04-11T20:54:27.818Z",
            "country": "Nigeria",
            "createdAt": "2022-11-03T14:16:54.235Z",
            "lastModifiedAt": "2022-11-03T14:16:54.235Z",
            "typeOfEntity": "",
            "registrationDate": "",
            "natureOfBusiness": null,
            "amlReport": null,
            "adverseMediaReport": null,
            "requestedBy": {
                "firstName": "Jamal",
                "lastName": "Akinyelu",
                "middleName": "",
                "id": "69b3c7f6556f687f7fb8a5c7"
            }
        }
    },
  "links": []
}

Error Response

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