Create Entity

This endpoint allows you to create an new entity using PII (Personally Identifiable Information), this can either be a business or an individual.

POST {{baseurl}}/v2/api/entities

Headers

Name	Type	Description
token*	String	API secret token

Request Body

Field	Type	Description
entityType*	String	Type of entity being verified. Allowed values: "individual", "business"
isSubjectConsent*	Boolean	Must always be true; indicates subject consent was obtained. Allowed values: true
incorporationNumber	String	Registration/Incorporation number, Required if entityType is "business".
incorporationName	String	Registered Name of business, Required if entityType is "business".
incorporationCountry	String	2-letter country code; allowed only for businesses.
incorporationDate	String	Incorporation date in YYYY-MM-DD format; allowed only for businesses.
businessType	String	Business type; allowed only for businesses.
address	String	Business address; allowed only for businesses.
docLink	String	Certificate of incorporation or business registration document; allowed only for businesses.
firstName	String	Individual's first name(Required for individual entity).
lastName	String	Individual's last name(Required for individual entity).
phone	String	Individual's phone number(Required for individual entity).
email	String	Individual's email
gender	String	Individual's gender.
dateOfBirth	String	Individual's date of birth in YYYY-MM-DD format(Required for individual entity).
nationality	String	2-letter country code(Required for individual entity).
imageUrl	String	Link to uploaded image
verifiedBy	String	Flag to ensure customer attests to validity of provided records. Allowed values: "client"

Create New Entity Sample Request (Individual)

{
    "entityType": "individual",
    "isSubjectConsent": true,
    "firstName": "John",
    "lastName": "Doe",
    "email": "[e-mail]",
    "phone": "[phone]",
    "gender": "male",
    "dateOfBirth": "1990-01-01",
    "nationality": "NG",
    "imageUrl": "http://someimage",
    "verifiedBy": "client"
}

Create New Entity Sample Request (Business)

Success Response

{
  "success": true,
  "status_code": 201,
  "message": "Entity created successfully.",
  "data": {
     "id": "ent_684f5cc5a47a3926763b83a7",
        "businessId": "61d880f1e8e15aaf24558f1a",
        "createdBy": {
            "firstName": "Timothy",
            "lastName": "Akinyelu",
            "middleName": "",
            "id": "61f162ec1fd251c3a63f31c2"
        }
  }
}

Error Response