Create an entity

POST

/entities

Creates a new entity representing a business or individual under the authenticated identity. Each entity must have a unique client_reference per identity. You may optionally attach a parent_id to model hierarchical entity relationships — the parent entity must already exist and belong to the same identity.

On successful creation the caller is automatically granted full ACL access (*: true) to the new entity, and if this is the caller's first entity it is also automatically set as the selected entity for the session.

The type and category values must match options configured in your account's static data (entity_types and entity_categories).

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

Entity created successfully. The caller is automatically granted full access to the new entity.

Bodyapplication/json

🟠400

🟠401

🟠404

🔴500

Request Example

Shell

JavaScript

Java

Swift

cURL

Required fields onlyAll fields including optional

curl --location '/entities' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Acme Corp Nigeria",
    "client_reference": "ent-ng-001",
    "type": "business",
    "category": "retail",
    "email": "contact@acmecorp.ng",
    "mobilenumber": "+2348012345678",
    "country": "NG"
}'

Response Example

201 - Success

{
    "message": "Entity created successfully",
    "status": "success",
    "data": {
        "id": "01JABC1234567890ABCDEFGHIJ",
        "parent_id": null,
        "name": "Acme Corp Nigeria",
        "client_reference": "ent-ng-001",
        "client_label": "Acme NG",
        "type": "business",
        "category": "retail",
        "email": "contact@acmecorp.ng",
        "mobilenumber": "+2348012345678",
        "country": "NG",
        "status": "approved",
        "kyc_status": "not_started",
        "identity_id": "01JIDENT234567890ABCDEFGHI",
        "entity_logo": "https://assets.acmecorp.ng/logo.png",
        "client_meta": {
            "crm_id": "crm-8821"
        }
    }
}

Modified at 2026-09-28 09:43:27

Create or update an app setting value

List entities