Entities - Nuvion

An entity represents a person or business onboarded to your platform. Entities must be created and approved before accounts can be opened for them.

The Entity object

string

Unique entity identifier.

string

individual or business.

string

Review state. One of incomplete, pending, approved, rejected, or suspended. A newly created entity is incomplete until it is submitted for review.

string

Display name for the entity.

boolean

Whether this entity is the top of its hierarchy, or a child of another entity.

string

The ID of the parent entity, when this entity was created under one.

string

The ID of the associated person record. Present only when type is individual.

string

The ID of the associated business record. Present only when type is business.

string

The ID of the user associated with this entity, when applicable.

string

How the entity was created. e.g. api, user.

string

The compliance risk band assigned to this entity. e.g. medium.

number

Unix timestamp in milliseconds when the entity was created.

number

Unix timestamp in milliseconds when the entity was last updated.

Identity details, business details, and metadata are not nested inside the entity object. They’re returned as sibling objects (person or business, and person_meta or business_meta) alongside entity in endpoint responses. See Get an entity.

Example

{
  "id": "01HXYZ0001ABCDEFGHJKMNPQRS",
  "type": "individual",
  "status": "approved",
  "name": "Alex Johnson",
  "is_root": false,
  "parent_entity": "01HXYZ1234ABCDEFGHJKMNPQRS",
  "person_id": "01HXYZ0002ABCDEFGHJKMNPQRS",
  "user_id": "01HXYZ0003ABCDEFGHJKMNPQRS",
  "creation_context": "api",
  "created": 1786965590981,
  "updated": 1786966136585
}

Create an individual entity

POST /individual-entities Creates a new individual entity. After creation, upload KYC documents and submit for onboarding review before the entity can open accounts.

curl -X POST https://api.nuvion.dev/individual-entities \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Johnson",
    "person": {
      "first_name": "Alex",
      "last_name": "Johnson",
      "Middle_name": "M",
      "date_of_birth": "1997-11-07",
      "email": "alex.johnson@example.com",
      "nationality": "NG",
      "gender": "m",
      "phonenumber": "+2348105391403",
      "bvn": "23487898752",
      "nin": "25856744238"
    },
    "address": {
      "line_1": "11 Opebi Road",
      "line_2": "Apt 4B",
      "line_3": "Suite 5C",
      "city": "Victoria Island",
      "state": "Lagos",
      "postal_code": "101241",
      "country_code": "NG"
    },
    "identification": {
      "document": {
        "type": "international_passport",
        "number": "P987653881",
        "issue_date": "2020-01-10",
        "expiry_date": "2030-01-09",
        "issuing_country": "NG",
        "issuing_authority": "Nigeria",
        "type_specific": {
          "id_subtype": "BVN"
        }
      },
      "proof_of_address": {
        "type": "utility_bill"
      }
    },
    "meta": {
      "funding_source": "salary",
      "monthly_transaction_value": "5000",
      "tax_id": "TAX-1234567890",
      "annual_turnover": "60000",
      "customer_types": "individual",
      "monthly_payments_count": "10",
      "max_transfer_amount": "10000",
      "sales_channels": "My own website"
    }
  }'

Request fields

string

required

A display name for the entity. 1–255 characters.

object

required

Personal details for the individual.

Show person fields

string

required

1–100 characters.

string

required

1–100 characters.

string

Max 100 characters.

string

required

Format: YYYY-MM-DD.

string

required

Valid email address.

string

required

ISO 3166-1 alpha-2 country code. e.g. US, GB, CA.

string

required

m for male, f for female.

string

Phone number including country code. 10–14 characters.

string

Bank Verification Number (BVN) required for Nigerian nationals.

string

National Identity Number (NIN) required for Nigerian nationals.

string

Social Security Number (SSN) required for U.S. nationals.

object

Residential address of the individual.

Show address fields

string

required

Street address line 1. 1–255 characters.

string

Street address line 2. Max 255 characters.

string

Street address line 3. Max 255 characters.

string

required

City. 1–100 characters.

string

required

State or province. 1–100 characters.

string

required

Postal or ZIP code. 1–20 characters.

string

required

ISO 3166-1 alpha-2 country code. e.g. US, GB, CA.

object

Additional address metadata.

object

Identity and address verification documents.

Show identification fields

object

Government-issued identity document.

Show document fields

string

required

Document type. One of international_passport, drivers_license, national_id.

string

required

Document number.

string

Date the document was issued. Format: YYYY-MM-DD.

string

Date the document expires. Format: YYYY-MM-DD.

string

ISO 3166-1 alpha-2 country code of the issuing authority.

string

Name of the authority that issued the document.

object

Additional fields for country-specific document types.

Show type_specific fields

string

Subtype for national ID documents. One of BVN, SSN, NIN.

object

Address verification document.

Show proof_of_address fields

string

required

One of utility_bill, bank_statement.

object

Business context for the individual, if applicable (e.g. a sole trader or freelancer).

Show business fields

string

required

Trading name. 1–100 characters.

string

required

Description of the business activity. 1–200 characters.

string

required

Business category code. 1–100 characters.

string

Business sub-category code. 1–100 characters.

string

Business website URL.

string

URL of a liveness or biometric report for this individual.

object

Additional compliance and risk metadata.

Show meta fields

string

Tax identification number.

string

Expected number of monthly payments.

string

Expected monthly transaction volume.

string

Maximum single transfer amount.

string

Estimated annual income or revenue.

string

Description of the individual’s customer base, if applicable.

string

Primary source of funds. e.g. salary, business_income, investments.

string

Description of this individual’s relationship to its parent, if associated with a business entity. 1–100 characters. You can’t set the parent via a request field: it’s always the authenticating entity. See Managing child entities.

Response

Returns the created entity object with status: "incomplete" until it is submitted for review.

Response

{
    "status": "success",
    "message": "Individual entity created successfully",
    "data": {
        "address": {
            "id": "01HXYZ0004ABCDEFGHJKMNPQRS",
            "line_1": "11 Opebi Road",
            "city": "Victoria Island",
            "state": "Lagos",
            "postal_code": "101241",
            "country_code": "NG",
            "owner_id": "01HXYZ0005ABCDEFGHJKMNPQRS",
            "owner_type": "person",
            "created": 1787485029923,
            "updated": 1787485029923
        },
        "entity": {
            "id": "01HXYZ0006ABCDEFGHJKMNPQRS",
            "type": "individual",
            "status": "incomplete",
            "name": "Alex Johnson",
            "is_root": false,
            "parent_entity": "01HXYZ1234ABCDEFGHJKMNPQRS",
            "user_id": "01HXYZ0003ABCDEFGHJKMNPQRS",
            "creation_context": "api",
            "risk_level": "medium",
            "created": 1787485030011,
            "updated": 1787485030011
        },
        "person": {
            "id": "01HXYZ0005ABCDEFGHJKMNPQRS",
            "first_name": "Alex",
            "last_name": "Johnson",
            "date_of_birth": "1997-11-07",
            "email": "alex.johnson@example.com",
            "nationality": "NG",
            "gender": "m",
            "is_pep": false,
            "status": "approved",
            "phonenumber": "+2348105391403",
            "created": 1787485029846,
            "updated": 1787485029846
        },
        "identification": {
            "id": "01HXYZ0007ABCDEFGHJKMNPQRS",
            "person_id": "01HXYZ0005ABCDEFGHJKMNPQRS",
            "verification_status": "pending",
            "created": 1787485030101,
            "updated": 1787485030101,
            "document": {
                "type": "international_passport",
                "number": "***3881",
                "issue_date": "2020-01-10",
                "expiry_date": "2030-01-09",
                "issuing_country": "NG",
                "issuing_authority": "Nigeria",
                "verification_status": "pending"
            },
            "proof_of_address": {
                "type": "utility_bill",
                "verification_status": "pending"
            },
            "identity_numbers": [
                {
                    "type": "BVN",
                    "value": "***8752",
                    "verification_status": "pending"
                },
                {
                    "type": "NIN",
                    "value": "***4238",
                    "verification_status": "pending"
                }
            ]
        }
    }
}

The response includes a data.person.id field used to associate KYC documents in the next step. See Entities guide for the full onboarding flow.

Update an individual entity

PATCH /individual-entities/{entity_id} Updates the profile of an existing individual entity.

curl -X PATCH https://api.nuvion.dev/individual-entities/01HXYZ2233ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alycia Bernhard",
    "person": {
      "first_name": "Alycia",
      "last_name": "Bernhard",
      "middle_name": "Jeremy93",
      "email": "simeon3@yopmail.net",
      "date_of_birth": "1990-01-15",
      "nationality": "GB",
      "gender": "m",
      "phonenumber": "+440099000912"
    }
  }'

Path parameters

string

required

The ID of the individual entity to update.

Request parameters

string

The name of the individual entity.

object

The profile details of the individual entity.

Show person fields

string

Legal first name of the individual.

string

Legal last name of the individual.

string

Contact email address. Must be a valid email format.

string

Date of birth in YYYY-MM-DD format (e.g. 1990-06-15).

string

ISO 3166-1 alpha-2 country code for the individual’s nationality (e.g. US).

string

The individual’s gender. m for male, f for female.

string

The individual’s phone number.

object

The address of the individual entity.

Show address fields

string

Street address line 1.

string

Street address line 2.

string

Street address line 3.

string

Additional address metadata.

string

City.

string

State/province/region.

string

Postal or ZIP code.

string

ISO 3166-1 alpha-2 country code (e.g. US).

object

Show business fields

string

Full registered legal name of the business.

string

Business contact name

string

Business liveness report url.

string

Business description.

string

The business’s industry category code (e.g. 5812 for restaurants).

string

The business’s industry sub-category code (e.g. 581208 for fast food restaurants).

object

The identification details of the individual entity.

Show identification fields

object

The identification document details.

Show document fields

string

Document type. One of international_passport, drivers_license, national_id.

string

The identification document number.

string

Issue date of the identification document in YYYY-MM-DD format (e.g. 2020-01-01).

string

Expiry date of the identification document in YYYY-MM-DD format (e.g. 2030-12-31).

string

ISO 3166-1 alpha-2 country code where the identification document was issued (e.g. US).

string

The authority that issued the identification document.

string

The ID of the uploaded identification document returned by the document upload endpoint.

object

Additional fields specific to the type of identification document.

Show type_specific fields

string

The subtype of the document (SSN, BVN,NIN).

object

The proof of address document details.

Show proof_of_address fields

string

The utility bill document type (utility_bill|bank_statement).

string

The ID of the uploaded proof of address document returned by the document upload endpoint.

string

Description of this individual’s relationship to its parent entity (e.g. director, owner, etc.). You can’t set the parent via a request field: it’s always the authenticating entity. See Managing child entities.

Sample Response

{
    "message": "Individual entity updated successfully",
    "status": "success",
    "data": {
        "changes_applied": {
            "entity_fields": [],
            "person_fields": [],
            "address_fields": [],
            "identification_fields": []
        },
        "address": {
            "id": "01HXYZ0008ABCDEFGHJKMNPQRS",
            "line_1": "456 Home Street",
            "line_2": "",
            "city": "London",
            "state": "BRY",
            "postal_code": "EC1A 1BB",
            "country_code": "NG",
            "owner_id": "01HXYZ0009ABCDEFGHJKMNPQRS",
            "owner_type": "person",
            "created": 1756735810827,
            "updated": 1767137386937
        },
        "entity": {
            "id": "01HXYZ0010ABCDEFGHJKMNPQRS",
            "type": "individual",
            "status": "approved",
            "name": "Alycia Bernhard",
            "is_root": false,
            "user_id": "01HXYZ0011ABCDEFGHJKMNPQRS",
            "creation_context": "user",
            "created": 1756735810827,
            "updated": 1770112256131
        },
        "person": {
            "id": "01HXYZ0009ABCDEFGHJKMNPQRS",
            "first_name": "Alycia",
            "last_name": "Bernhard",
            "middle_name": "Jeremy93",
            "date_of_birth": "1990-01-15",
            "email": "simeon3@yopmail.net",
            "nationality": "GB",
            "gender": "m",
            "is_pep": false,
            "status": "approved",
            "phonenumber": "+440099000912",
            "created": 1756735810753,
            "updated": 1767140718015
        },
        "identification": {
            "id": "01HXYZ0012ABCDEFGHJKMNPQRS",
            "person_id": "01HXYZ0009ABCDEFGHJKMNPQRS",
            "verification_status": "pending",
            "created": 1767140794026,
            "updated": 1767140793956,
            "proof_of_address": {
                "type": "utility_bill",
                "document_id": "01HXYZ0013ABCDEFGHJKMNPQRS",
                "verification_status": "pending"
            }
        }
    }
}

Response fields

string

A message describing the result of the update operation.

string

The status of the update operation.

object

The updated entity data.

Show data

object

The specific fields that were updated in the entity, person, address, and identification objects.

array

The updated address object for the individual entity.

array

The updated entity object for the individual entity.

array

The updated person object for the individual entity.

array

The updated identification object for the individual entity.

object

The updated address details of the individual entity.

Show address fields

string

Street address line 1.

string

Street address line 2.

string

Street address line 3.

string

Additional address metadata.

string

City.

string

State/province/region.

string

Postal or ZIP code.

string

ISO 3166-1 alpha-2 country code (e.g. US).

string

The ID of the owner of the address (person or business).

string

The type of the owner of the address (person or business).

number

Unix timestamp in milliseconds when the address was created.

number

Unix timestamp in milliseconds when the address was last updated.

object

The updated entity details of the individual entity.

Show entity fields

string

Unique entity identifier.

string

individual or business.

string

Review state. One of incomplete, pending, approved, rejected, or suspended.

string

The name of the individual entity.

boolean

Indicates if this entity is a root entity in a hierarchical relationship.

string

The ID of the user associated with this entity, if applicable.

string

The context in which the entity was created (e.g. “user”, “admin”, “api”).

number

Unix timestamp in milliseconds when the entity was created.

number

Unix timestamp in milliseconds when the entity was last updated.

object

The updated person details of the individual entity.

Show person fields

string

Legal first name of the individual.

string

Legal last name of the individual.

string

Middle name of the individual.

string

Date of birth in YYYY-MM-DD format (e.g. 1990-06-15).

string

Contact email address. Must be a valid email format.

string

ISO 3166-1 alpha-2 country code for the individual’s nationality (e.g. US).

string

The individual’s gender. One of m, f.

boolean

Indicates if the individual is a politically exposed person (PEP).

string

The review status of the individual’s profile. One of pending, approved, rejected, or suspended.

string

The individual’s phone number.

number

Unix timestamp in milliseconds when the person profile was created.

number

Unix timestamp in milliseconds when the person profile was last updated.

object

The updated identification details of the individual entity.

Show identification fields

string

The overall verification status of the individual’s identification. One of pending, approved, rejected, or suspended.

number

Unix timestamp in milliseconds when the identification details were created.

number

Unix timestamp in milliseconds when the identification details were last updated.

object

The updated proof of address document details.

Show proof_of_address fields

string

The utility bill document type (utility_bill | bank_statement).

string

The ID of the uploaded proof of address document returned by the document upload endpoint.

string

The verification status of the proof of address document. One of pending, approved, rejected, or suspended.

Create a business entity

POST /business-entities Creates a new business entity. After creation, submit for KYB onboarding review before the entity can open accounts.

curl -X POST https://api.nuvion.dev/business-entities \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "App Business Ltd",
    "business": {
      "legal_name": "App Technologies Limited",
      "trade_name": "App Tech",
      "industry": "Technology",
      "email": "finance@acmetech.com",
      "website": "https://acmetech.com",
      "type": "llc",
      "description": "A B2B SaaS platform for logistics management.",
      "registration_number": "47-7654334",
      "phonenumber": "+12125550199",
      "incorporation_meta": {
        "year": 2019,
        "month": 4,
        "country": "US",
        "state": "Delaware"
      }
    },
    "address": {
      "line_1": "350 Fifth Avenue",
      "city": "New York",
      "state": "New York",
      "postal_code": "10118",
      "country_code": "US"
    },
    "operating_address": {
      "line_1": "350 Fifth Avenue",
      "city": "New York",
      "state": "New York",
      "postal_code": "10118",
      "country_code": "US"
    },
    "business_officers": [
      {
        "job_title": "Chief Executive Officer",
        "is_control_person": true,
        "is_beneficial_owner": true,
        "ownership_percentage": 60,
        "person": {
          "first_name": "Alex",
          "last_name": "Johnson",
          "date_of_birth": "1985-06-15",
          "email": "alex.johnson@acmetech.com",
          "nationality": "US",
          "gender": "m",
          "phonenumber": "+12125550198",
          "bvn": "23487892834",
          "nin": "25856743645",
          "ssn": "123-45-6789",
          "identification": {
            "document": {
              "type": "international_passport",
              "number": "P123456789",
              "issue_date": "2020-01-10",
              "expiry_date": "2030-01-09",
              "issuing_country": "US"
            },
            "proof_of_address": {
              "type": "utility_bill"
            }
          },
          "address": {
            "line_1": "210 West 77th Street",
            "city": "New York",
            "state": "New York",
            "postal_code": "10024",
            "country_code": "US"
          }
        }
      }
    ],
    "meta": {
      "registration_number": "47-7654334",
      "tax_id": "47-1234589",
      "annual_turnover": "5M",
      "monthly_transaction_value": "500K",
      "monthly_payments_count": "200",
      "max_transfer_amount": "100K",
      "customer_types": "Individual",
      "sales_channels": ["physical_store", "E-commerce platform or marketplace", "social media page", "My own website"],
      "funding_source": "Revenue from software subscriptions",
      "liveness_check_id": "liv_01HXYZ1234ABCD"
    }
  }'

Request fields

string

required

A display name for the entity. 1–255 characters.

object

required

Core business information.

Show business fields

string

required

The entity’s registered legal name. 1–255 characters.

string

Trading name or DBA, if different from the legal name. Max 255 characters.

string

The industry the business operates in. 1–100 characters.

string

required

Business contact email address.

string

required

Business website URL.

string

required

Legal structure of the business. e.g. llc, corporation, partnership, sole_proprietorship.

string

required

A description of what the business does. 1–1000 characters.

string

required

Government-issued business registration number. 1–255 characters.

string

required

Business phone number including country code. 10–14 characters.

object

required

Details of when and where the business was incorporated.

Show incorporation_meta fields

number

required

Year of incorporation.

number

Month of incorporation. 1–12.

string

required

ISO 3166-1 alpha-2 country code of incorporation. e.g. NG, US.

string

State or province of incorporation. 1–100 characters.

object

Registered address of the business.

Show address fields

string

required

Street address line 1. 1–255 characters.

string

Street address line 2. Max 255 characters.

string

Street address line 3. Max 255 characters.

string

required

City. 1–100 characters.

string

required

State or province. 1–100 characters.

string

required

Postal or ZIP code. 1–20 characters.

string

required

ISO 3166-1 alpha-2 country code. e.g. NG, US, GB.

object

Additional address metadata.

object

The address where the business physically operates, if different from the registered address. Same structure as address.

array

The individuals associated with the business. At least one officer is required.

Show business_officers fields

string

required

The officer’s title within the organization. 1–100 characters.

boolean

required

Whether this person has significant management control over the business.

boolean

required

Whether this person owns 25% or more of the business.

number

required

The officer’s ownership stake. 0–100.

object

Personal details for the officer. See Person object below.

object

Additional compliance and business metadata.

Show meta fields

string

Government-issued registration number, if not provided in the business object.

string

Tax identification number.

string

required

Estimated annual revenue.

string

required

Expected monthly transaction volume.

string

required

Expected number of monthly payments.

string

required

Maximum single transfer amount.

string

required

Description of the business’s customer base.

string | array

Channels through which the business sells (e.g. online, in-person). A single string or an array of strings.

string

required

Primary source of funds for the business.

string

Reference ID from a liveness or biometric check.

string

The ID of the parent entity, if this entity was created by another entity’s API key. Always the authenticating entity at creation; not settable via a request field.

Person object

The person object is used within business_officers to capture individual details.

string

required

1–100 characters.

string

required

1–100 characters.

string

Max 100 characters.

string

required

Format: YYYY-MM-DD.

string

required

Valid email address.

string

required

ISO 3166-1 alpha-2 country code. e.g. NG, GH, US.

string

required

m for male, f for female.

string

Phone number including country code. 10–14 characters.

string

Bank Verification Number (BVN) required for Nigerian nationals.

string

National Identity Number (NIN) required for Nigerian nationals.

string

Social Security Number (SSN) required for U.S. nationals.

object

Identity verification documents for this person.

Show identification fields

object

required

Government-issued identity document. Must be from a non-sanctioned country.

Show document fields

string

required

Document type. One of international_passport, drivers_license, national_id.

string

required

Document number.

string

Date the document was issued. Format: YYYY-MM-DD.

string

Date the document expires. Format: YYYY-MM-DD.

string

ISO 3166-1 alpha-2 country code of the issuing authority.

string

Name of the authority that issued the document.

object

Additional fields for country-specific document types.

Show type_specific fields

string

Subtype for national ID documents. One of BVN, SSN, NIN.

object

Address verification document.

Show proof_of_address fields

string

required

One of utility_bill, bank_statement.

object

Residential address of this person. Same structure as the business address object.

Response

Returns the created entity object with type: "business" and status: "incomplete" until it is submitted for review.

Response

{
    "status": "success",
    "message": "Business entity created successfully",
    "data": {
        "address": {
            "id": "01HXYZ0014ABCDEFGHJKMNPQRS",
            "line_1": "350 Fifth Avenue",
            "city": "New York",
            "state": "New York",
            "postal_code": "10118",
            "country_code": "US",
            "owner_id": "01HXYZ0015ABCDEFGHJKMNPQRS",
            "owner_type": "business",
            "created": 1787487224804,
            "updated": 1787487224804
        },
        "entity": {
            "id": "01HXYZ0016ABCDEFGHJKMNPQRS",
            "type": "business",
            "status": "incomplete",
            "name": "App Business Ltd",
            "is_root": false,
            "parent_entity": "01HXYZ1234ABCDEFGHJKMNPQRS",
            "business_id": "01HXYZ0015ABCDEFGHJKMNPQRS",
            "user_id": "01HXYZ0003ABCDEFGHJKMNPQRS",
            "creation_context": "api",
            "risk_level": "medium",
            "created": 1787487225040,
            "updated": 1787487225040
        },
        "operating_address": {
            "id": "01HXYZ0017ABCDEFGHJKMNPQRS",
            "line_1": "350 Fifth Avenue",
            "city": "New York",
            "state": "New York",
            "postal_code": "10118",
            "country_code": "US",
            "owner_id": "01HXYZ0015ABCDEFGHJKMNPQRS",
            "owner_type": "business",
            "created": 1787487225110,
            "updated": 1787487225110
        },
        "business": {
            "id": "01HXYZ0015ABCDEFGHJKMNPQRS",
            "legal_name": "App Technologies Limited",
            "trade_name": "App Tech",
            "email": "finance@acmetech.com",
            "phonenumber": "+12125550199",
            "registration_number": "47-7654334",
            "industry": "Technology",
            "website": "https://acmetech.com",
            "type": "llc",
            "description": "A B2B SaaS platform for logistics management.",
            "incorporation_meta": {
                "year": 2019,
                "month": 4,
                "country": "US",
                "state": "Delaware"
            },
            "created": 1787487224651,
            "updated": 1787487224651
        },
        "business_meta": {
            "id": "01HXYZ0018ABCDEFGHJKMNPQRS",
            "business_id": "01HXYZ0015ABCDEFGHJKMNPQRS",
            "meta": {
                "registration_number": "47-7654334",
                "tax_id": "47-1234589",
                "monthly_transaction_value": "500K",
                "monthly_payments_count": "200",
                "max_transfer_amount": "100K",
                "annual_turnover": "5M",
                "customer_types": "Individual",
                "sales_channels": ["physical_store", "E-commerce platform or marketplace", "social media page", "My own website"],
                "funding_source": "Revenue from software subscriptions"
            },
            "created": 1787487224960,
            "updated": 1787487224960
        },
        "business_officers": [
            {
                "id": "01HXYZ0019ABCDEFGHJKMNPQRS",
                "person_id": "01HXYZ0005ABCDEFGHJKMNPQRS",
                "job_title": "Chief Executive Officer",
                "is_control_person": true,
                "is_beneficial_owner": true,
                "ownership_percentage": 60,
                "business_id": "01HXYZ0015ABCDEFGHJKMNPQRS",
                "created": 1787487224875,
                "updated": 1787487224875
            }
        ]
    }
}

Upload a KYC document

POST /documents Upload a supporting document for identity or business verification. Documents must be passed as base64-encoded strings.

Required documents vary by entity type. See Creating an individual entity or Creating a business entity for the full list per entity type.

curl -X POST https://api.nuvion.dev/documents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ0006ABCDEFGHJKMNPQRS",
    "key": "identity",
    "description": "International passport for Alex Johnson",
    "file": "base64_encoded_front_here",
    "file_back": "base64_encoded_back_here",
    "meta": {
      "file_type": "application/pdf"
    },
    "link_to_identity": {
      "person_id": "01HXYZ0005ABCDEFGHJKMNPQRS"
    }
  }'

curl -X POST https://api.nuvion.dev/documents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ0006ABCDEFGHJKMNPQRS",
    "key": "proof_of_address",
    "description": "Utility bill for Alex Johnson",
    "file": "base64_encoded_content_here",
    "meta": {
      "file_type": "application/pdf"
    },
    "link_to_identity": {
      "person_id": "01HXYZ0005ABCDEFGHJKMNPQRS"
    }
  }'

Request parameters

string

required

Document type. One of identity, proof_of_address, tax_verification, certificate_of_incorporation, or memorandum_of_association.

string

required

A short description of the document. 1–500 characters.

string

required

The person_id returned in the response when the individual entity was created.

file

required

The document file. Accepted formats: PDF, JPG, PNG. Maximum file size: 10 MB.

Response

{
    "status": "success",
    "message": "Document submitted successfully",
    "data": {
        "document": {
            "id": "01HXYZ0020ABCDEFGHJKMNPQRS",
            "entity_id": "01HXYZ0006ABCDEFGHJKMNPQRS",
            "key": "proof_of_address",
            "description": "Utility Bill",
            "urls": {
                "main": "https://files.example.invalid/entity-documents/01HXYZ0006ABCDEFGHJKMNPQRS/1787487450319-piz8q5sodno"
            },
            "meta": {
                "file_type": "image/jpeg",
                "verification_status": "pending",
                "uploaded_at": 1787487450870
            },
            "created": 1787487450870,
            "updated": 1787487450870
        },
        "entity_verification_impact": {
            "entity_id": "01HXYZ0006ABCDEFGHJKMNPQRS"
        }
    }
}

Upload every document required for the entity’s type before calling the onboarding submission endpoint.

Submit for onboarding review

POST /onboarding-submissions Submit an entity for KYC or KYB review. For individual entities, call this after uploading all required documents. For business entities, call this after providing full business details.

curl -X POST https://api.nuvion.dev/onboarding-submissions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ0016ABCDEFGHJKMNPQRS"
  }'

Request parameters

string

required

The ID of the entity to submit for review.

Response

Returns the entity object with status: "pending". Nuvion reviews the submission asynchronously and fires a webhook when the status changes to approved or rejected.

Response

{
    "status": "success",
    "message": "Onboarding completed successfully",
    "data": {
        "entity": {
            "id": "01HXYZ0016ABCDEFGHJKMNPQRS",
            "type": "business",
            "status": "pending",
            "name": "App Business Ltd",
            "is_root": false,
            "parent_entity": "01HXYZ1234ABCDEFGHJKMNPQRS",
            "business_id": "01HXYZ0015ABCDEFGHJKMNPQRS",
            "user_id": "01HXYZ0003ABCDEFGHJKMNPQRS",
            "creation_context": "api",
            "created": 1787487225040,
            "updated": 1787487225040
        }
    }
}

Update a business entity

PATCH /business-entities/{entity_id} Updates the profile of an existing business entity.

curl -X PATCH https://api.nuvion.dev/business-entities/01HXYZ3344ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Entity display name",
    "business": {
      "legal_name": "Acme example Ltd",
      "trade_name": "AcmeExample",
      "website": "https://www.example.com",
      "description": "A description of the business",
      "type": "business structure type",
      "phonenumber": "business phone number",
      "email": "accounts@examplecorp.com",
      "registration_number": "business registration number",
      "incorporation_meta": {
        "year": "2020",
        "month": "01",
        "country": "US",
        "state": "NY"
      }
    },
    "address": {
      "line_1": "456 Business Ave",
      "line_2": "Suite 100",
      "line_3": "Attn: Jane Smith",
      "meta": "Additional address metadata",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country_code": "US"
    },

    "operating_address": {
      "line_1": "789 Commerce St",
      "line_2": "Floor 5",
      "line_3": "Attn: John Doe",
      "meta": "Additional address metadata",
      "city": "New York",
      "state": "NY",
      "postal_code": "10002",
      "country_code": "US"
    },

    "business_officers": [
      { 
      "id": "", //string - required for updating an existing officer, not needed when adding a new officer
      "person_id": "", //string - required when adding a new officer to link to an existing individual entity
      "job_title": "", //string
      "is_control_person": true, //boolean
      "is_beneficial_owner": true, //boolean
      "ownership_percentage": 50, //number
      "action": "add", // "add" to add a new officer, "update" to update an existing officer, "remove" to remove an officer
      "person":
        {
        "meta":{},
          "first_name": "Jane",
          "last_name": "Smith",
          "middle_name": "",
          "date_of_birth": "1990-06-15",
          "email": "",
          "nationality": "US",
          "gender": "f",
          "identification": {
            "document": {
              "type": "international_passport",
              "number": "123456789",
              "issue_date": "2020-01-01",
              "expiry_date": "2030-12-31",
              "issuing_country": "US",
              "issuing_authority": "US Department of State",
              "document_id": "01HXYZ0046ABCDEFGHJKMNPQRS",
              "type_specific": {
                "id_subtype": "SSN|BVN|NIN"
              }
            },
            "Proof_of_address": {
              "type": "utility_bill|bank_statement",
              "document_id": "01HXYZ0047ABCDEFGHJKMNPQRS"
            }
          },
          "address": {
            "line_1": "456 Business Ave",
            "line_2": "Suite 100",
            "line_3": "Attn: Jane Smith",
            "meta": "Additional address metadata",
            "city": "New York",
            "state": "NY",
            "postal_code": "10001",
            "country_code": "US"
          } 
          
        }
      }
    ], 
      "meta": {
        "registration_number": "business registration number",
        "tax_id": "", //string
        "liveness_check_id": "", //string - the ID of a liveness check report to link to the business entity for KYB review
        "monthly_payment_count": "", //number - the number of payments processed by the business in the past month to provide additional context for KYB review
        "monthly_transaction_value": "", //number - the total value of payments processed by the business in the past month to provide additional context for KYB review
        "max_transfer_amount": "", //number - the maximum amount the business expects to transfer in a single payment to provide additional context for KYB review
        "annual_turnover": "", //number - the annual turnover of the business to provide additional context for KYB review
        "customer_types": "", //string - the types of customers the business serves (e.g. "individuals", "other businesses", "nonprofits", etc.) to provide additional context for KYB review
        "sales_channels": "", //string - the channels through which the business sells (e.g. "online", "in-person", "both"). A single string or an array of strings.
        "funding_sources": "" //string - the primary funding sources for the business (e.g. "bank account", "credit card", "both") to provide additional context for KYB review
      },
      "parent_relationship": "" //string - the relationship of the business to the parent entity (e.g. "subsidiary", "affiliate", etc.)
  }'

Path parameters

string

required

The ID of the business entity to update.

Request parameters

string

The name of the business entity.

object

The profile details of the business entity.

Show business fields

string

Full registered legal name of the business as it appears on incorporation documents.

string

The name the business operates under if different from legal_name (DBA).

string

The business’s website URL.

string

A description of the business.

string

Legal structure of the business. One of llc, corporation, partnership, or sole_proprietorship.

string

The business’s phone number.

string

The business’s contact email address.

string

The business’s registration number from the government authority where it is incorporated.

object

Additional details about the business’s incorporation.

Show incorporation_meta fields

string

The year the business was incorporated (e.g. “2020”).

string

The month the business was incorporated (e.g. “01” for January).

string

ISO 3166-1 alpha-2 country code where the business is incorporated (e.g. “US”).

string

State or province where the business is incorporated, if applicable (e.g. “NY”).

object

The registered address of the business.

Show address fields

string

Street address line 1.

string

Street address line 2.

string

Street address line 3.

string

Additional address metadata.

string

City.

string

State or province.

string

Postal or ZIP code.

string

ISO 3166-1 alpha-2 country code (e.g. US).

object

The operating address of the business if different from the registered address.

Show operating_address fields

string

Street address line 1.

string

Street address line 2.

string

Street address line 3.

string

Additional address metadata.

string

City.

string

State or province.

string

Postal or ZIP code.

string

ISO 3166-1 alpha-2 country code (e.g. US).

array

A list of the business’s officers and their details.

Show business_officers fields

string

The ID of the business officer. Required when updating an existing officer, not needed when adding a new officer.

string

The ID of the individual entity associated with this officer. Required when adding a new officer to link to an existing individual entity.

string

The officer’s job title (e.g. “CEO”, “Director”, etc.).

boolean

Whether the officer is a control person for the business.

boolean

Whether the officer is a beneficial owner of the business.

number

The percentage of ownership the officer has in the business, if applicable.

string

The action to perform for this officer. “add” to add a new officer, “update” to update an existing officer, “remove” to remove an officer.

object

Additional metadata about the business entity to provide more context for KYB review.

Show meta fields

string

The business’s registration number from the government authority where it is incorporated.

string

The business’s tax identification number.

string

The ID of a liveness check report to link to the business entity for KYB review.

number

The number of payments processed by the business in the past month to provide additional context for KYB review.

number

The total value of payments processed by the business in the past month to provide additional context for KYB review.

number

The maximum amount the business expects to transfer in a single payment to provide additional context for KYB review.

number

The annual turnover of the business to provide additional context for KYB review.

string

The types of customers the business serves (e.g. “individuals”, “other businesses”, “nonprofits”, etc.) to provide additional context for KYB review.

string | array

The channels through which the business sells (e.g. “online”, “in-person”, “both”) to provide additional context for KYB review. A single string or an array of strings.

string

The primary funding sources for the business (e.g. “bank account”, “credit card”, “both”) to provide additional context for KYB review.

string

Description of this business’s relationship to its parent entity (e.g. “subsidiary”, “affiliate”, etc.). You can’t set the parent via a request field: it’s always the authenticating entity. See Managing child entities.

Response fields

{
    "message": "Business entity updated successfully",
    "status": "success",
    "data": {
        "changes_applied": {
            "meta_fields": [],
            "entity_fields": [],
            "address_fields": [],
            "officers_added": [],
            "business_fields": [],
            "officers_removed": [],
            "officers_updated": []
        },
        "address": {
            "id": "01HXYZ0021ABCDEFGHJKMNPQRS",
            "line_1": "Test Lane",
            "line_2": "",
            "city": "Southampton",
            "state": "England",
            "postal_code": "SO14 0AA",
            "country_code": "GB",
            "owner_id": "01HXYZ0022ABCDEFGHJKMNPQRS",
            "owner_type": "business",
            "created": 1760622823855,
            "updated": 1762164348422
        },
        "entity": {
            "id": "01HXYZ0023ABCDEFGHJKMNPQRS",
            "type": "business",
            "status": "failed",
            "name": "Acme Corporation Ltd Configurable",
            "is_root": true,
            "business_id": "01HXYZ0022ABCDEFGHJKMNPQRS",
            "user_id": "01HXYZ0011ABCDEFGHJKMNPQRS",
            "creation_context": "user",
            "created": 1760622823856,
            "updated": 1762164393797
        },
        "operating_address": {
            "id": "69087e7c37ddf58d76abd5bf",
            "line_1": "Test Lane",
            "line_2": "",
            "city": "Southampton",
            "state": "England",
            "postal_code": "SO14 0AA",
            "country_code": "GB",
            "owner_id": "01HXYZ0022ABCDEFGHJKMNPQRS",
            "owner_type": "business",
            "created": 1762164348423,
            "updated": 1762164348422
        },
        "business": {
            "id": "01HXYZ0022ABCDEFGHJKMNPQRS",
            "legal_name": "Acme Corporation Ltd Configurable",
            "trade_name": "Acme Corp Optional",
            "email": "acme.corp@yopmail.net",
            "phonenumber": "+2348100000000",
            "registration_number": "123456790",
            "industry": "0763",
            "website": "https://acmecorp-test.com",
            "type": "LLC",
            "description": "Technology solutions provider",
            "incorporation_meta": {
                "year": 2020,
                "month": 1,
                "country": "US",
                "state": "England"
            },
            "created": 1760622823700,
            "updated": 1762164303860
        },
        "business_meta": {
            "id": "01HXYZ0024ABCDEFGHJKMNPQRS",
            "business_id": "01HXYZ0022ABCDEFGHJKMNPQRS",
            "meta": {
                "tax_id": "123456789",
                "proof_of_address": "https://files.example.invalid/image/upload/v1762122872/nuvion/business/documents/tzvukdiiomb2sjf9aqxy.png",
                "incorporation_document": "https://files.example.invalid/image/upload/v1762122855/nuvion/business/incorporation/awvweye2jeehqclihpe0.png",
                "mou_document": "https://files.example.invalid/image/upload/v1762122860/nuvion/business/documents/hg07oel1t00vleuvcjqo.png",
                "use_case": "",
                "registration_number": "123456790"
            },
            "created": 1760622823855,
            "updated": 1762164303929
        },
        "business_officers": [
            {
                "id": "01HXYZ0025ABCDEFGHJKMNPQRS",
                "person_id": "01HXYZ0026ABCDEFGHJKMNPQRS",
                "job_title": "ceo",
                "is_control_person": true,
                "is_beneficial_owner": true,
                "ownership_percentage": 55,
                "business_id": "01HXYZ0022ABCDEFGHJKMNPQRS",
                "created": 1760622823855,
                "updated": 1760636638066
            }
        ]
    }
}

string

A human-readable message describing the result of the API call.

string

The status of the API call. Either success or error.

object

The details of the updated entity, including all related objects and the specific changes that were applied.

Show data

object

The list of changes applies

Show changes_applied

array

List of meta fields that were updated.

array

List of entity fields that were updated.

array

List of address fields that were updated.

array

List of officers that were added.

array

List of business fields that were updated.

array

List of officers that were removed.

array

List of officers that were updated.

object

The entity’s registered address object.

Show address

string

Unique identifier for the address.

string

Street address line 1.

string

Street address line 2.

string

City.

string

State or province.

string

Postal or zip code.

string

Country.

object

The main entity object with core details and status.

Show entity

string

Unique identifier for the entity.

string

The entity type. Either individual or business.

string

The entity’s current verification status.

string

The display name of the entity.

boolean

Whether this entity is a root entity or a subsidiary.

string

The ID of the associated business object, if applicable.

string

The ID of the user who created this entity, if applicable.

string

How this entity was created (e.g. user, api).

object

Show operating_addres

string

Unique identifier for the operating address.

string

Street address line 1.

string

Street address line 2.

string

City.

string

State or province.

string

Postal or zip code.

string

Country.

string

The ID of the entity that owns this address.

string

The type of entity that owns this address (e.g. business).

number

The timestamp when this address was created.

number

The timestamp when this address was last updated.

object

The business-specific details for this entity.

Show business

string

Unique identifier for the business details object.

string

The registered legal name of the business.

string

The trading name or DBA of the business.

string

The contact email for the business.

string

The contact phone number for the business.

string

The government-issued registration number for the business.

string

The industry code or description for the business.

string

The website URL for the business.

string

The legal structure of the business (e.g. LLC, corporation).

string

A description of what the business does.

object

Additional details about the business’s incorporation.

Show incorporation_meta

number

The year the business was incorporated.

number

The month the business was incorporated.

string

The country where the business was incorporated.

string

The state or province where the business was incorporated.

number

The timestamp when these business details were created.

number

The timestamp when these business details were last updated.

object

Additional metadata related to the business entity.

Show business_meta

string

Unique identifier for the business meta object.

string

The ID of the associated business details object.

object

A key-value store for additional metadata about the business.

Show meta

string

The tax identification number for the business.

string

A URL to the proof of address document for the business.

string

A URL to the incorporation document for the business.

string

A URL to the memorandum of understanding document for the business.

string

A description of the business’s use case for Nuvion.

string

The government-issued registration number for the business.

number

The timestamp when this business meta was created.

number

The timestamp when this business meta was last updated.

array

A list of the business officers associated with this entity.

Show business_officers

string

Unique identifier for the business officer record.

string

The ID of the person associated with this officer.

string

The job title of the officer within the business.

boolean

Whether this officer has significant control over the business.

boolean

Whether this officer is a beneficial owner of the business.

number

The percentage of ownership this officer has in the business.

string

The ID of the associated business details object.

number

The timestamp when this business officer record was created.

number

The timestamp when this business officer record was last updated.

Get an entity

GET /entities/{entity_id} Retrieves an existing entity by ID.

curl https://api.nuvion.dev/entities/01HXYZ0001ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY"

Path parameters

string

required

The ID of the entity to retrieve.

Response

Returns the full entity record: the core entity object, the associated person or business record, addresses, identification, uploaded documents, and platform metadata. Business entities also include officers and child entities. Shape depends on type.

{
  "status": "success",
  "message": "Entity retrieved successfully",
  "data": {
    "entity": {
      "id": "01HXYZ0001ABCDEFGHJKMNPQRS",
      "type": "individual",
      "status": "approved",
      "name": "DemoOne Individual",
      "is_root": false,
      "parent_entity": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "person_id": "01HXYZ0002ABCDEFGHJKMNPQRS",
      "user_id": "01HXYZ0003ABCDEFGHJKMNPQRS",
      "creation_context": "api",
      "created": 1786965590981,
      "updated": 1786966136585
    },
    "person": {
      "id": "01HXYZ0002ABCDEFGHJKMNPQRS",
      "is_pep": false,
      "first_name": "Peter",
      "last_name": "Abo",
      "date_of_birth": "1997-11-07",
      "email": "individualr1@email.com",
      "nationality": "NG",
      "gender": "m",
      "status": "approved",
      "phonenumber": "+2348105391403",
      "created": 1786965590820,
      "updated": 1786965590820
    },
    "addresses": [
      {
        "id": "01HXYZ0027ABCDEFGHJKMNPQRS",
        "city": "Victoria Island",
        "state": "Lagos",
        "postal_code": "101241",
        "country_code": "NG",
        "line_1": "11 Opebi Road",
        "owner_id": "01HXYZ0002ABCDEFGHJKMNPQRS",
        "owner_type": "person",
        "label": "registered_address",
        "created": 1786965590897,
        "updated": 1786965590897
      }
    ],
    "identification": {
      "id": "01HXYZ0028ABCDEFGHJKMNPQRS",
      "person_id": "01HXYZ0002ABCDEFGHJKMNPQRS",
      "verification_status": "pending",
      "created": 1786965591070,
      "updated": 1786966116922,
      "document": {
        "type": "international_passport",
        "number": "***3881",
        "issue_date": "2020-01-10",
        "expiry_date": "2030-01-09",
        "issuing_country": "NG",
        "issuing_authority": "Nigeria",
        "verification_status": "pending",
        "document_id": "01HXYZ0029ABCDEFGHJKMNPQRS"
      },
      "proof_of_address": {
        "type": "utility_bill",
        "document_id": "01HXYZ0030ABCDEFGHJKMNPQRS",
        "verification_status": "pending"
      },
      "identity_numbers": [
        {
          "type": "BVN",
          "value": "***8752",
          "verification_status": "pending"
        },
        {
          "type": "NIN",
          "value": "***4238",
          "verification_status": "pending"
        }
      ]
    },
    "person_meta": {
      "id": "01HXYZ0031ABCDEFGHJKMNPQRS",
      "person_id": "01HXYZ0002ABCDEFGHJKMNPQRS",
      "meta": {
        "funding_source": "salary",
        "monthly_transaction_value": "500",
        "tax_id": "570225979",
        "annual_turnover": "1000",
        "customer_types": "individual",
        "monthly_payments_count": "5",
        "max_transfer_amount": "10000",
        "sales_channels": "My own website"
      },
      "created": 1786965591167,
      "updated": 1786965591167
    },
    "documents": [
      {
        "id": "01HXYZ0029ABCDEFGHJKMNPQRS",
        "key": "identity",
        "description": "International Passport",
        "urls": {
          "main": "https://files.example.invalid/entity-documents/01HXYZ0001ABCDEFGHJKMNPQRS/1786966098502-nlt85c7nefj"
        },
        "meta": {
          "file_type": "image/jpeg",
          "content_hash": "bc1d7e6d12319d45fc8270105a69e2af758feec26f7e034fe85b55623b748b7b"
        },
        "created": 1786966098903,
        "updated": 1786966098903
      },
      {
        "id": "01HXYZ0030ABCDEFGHJKMNPQRS",
        "key": "proof_of_address",
        "description": "Utility Bill",
        "urls": {
          "main": "https://files.example.invalid/entity-documents/01HXYZ0001ABCDEFGHJKMNPQRS/1786966116180-hdk40wq9ae"
        },
        "meta": {
          "file_type": "image/jpeg",
          "content_hash": "f7f7d2d943c1e2d6772197f30c985a61fef7f0f1dbad52e3b6dee0346b0f39c4"
        },
        "created": 1786966116782,
        "updated": 1786966116782
      }
    ],
    "child_entities": []
  }
}

{
  "status": "success",
  "message": "Entity retrieved successfully",
  "data": {
    "entity": {
      "id": "01HXYZ0032ABCDEFGHJKMNPQRS",
      "type": "business",
      "status": "approved",
      "name": "App Business Ltd",
      "is_root": false,
      "parent_entity": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "business_id": "01HXYZ0033ABCDEFGHJKMNPQRS",
      "user_id": "01HXYZ0034ABCDEFGHJKMNPQRS",
      "creation_context": "api",
      "created": 1786095703559,
      "updated": 1786095813891
    },
    "business": {
      "id": "01HXYZ0033ABCDEFGHJKMNPQRS",
      "email": "finance33@acmetech.com",
      "legal_name": "App Technologies Limited",
      "trade_name": "App Tech",
      "phonenumber": "+12125550199",
      "industry": "Technology",
      "website": "https://acmetech.com",
      "type": "llc",
      "description": "A B2B SaaS platform for logistics management.",
      "registration_number": "47-7654333",
      "incorporation_meta": {
        "year": 2019,
        "month": 4,
        "country": "US",
        "state": "Delaware"
      },
      "created": 1786095703200,
      "updated": 1786095703200
    },
    "addresses": [
      {
        "id": "01HXYZ0035ABCDEFGHJKMNPQRS",
        "city": "New York",
        "state": "New York",
        "postal_code": "10118",
        "country_code": "US",
        "line_1": "350 Fifth Avenue",
        "owner_id": "01HXYZ0033ABCDEFGHJKMNPQRS",
        "owner_type": "business",
        "label": "registered_address",
        "created": 1786095703345,
        "updated": 1786095703345
      },
      {
        "id": "01HXYZ0036ABCDEFGHJKMNPQRS",
        "city": "New York",
        "state": "New York",
        "postal_code": "10118",
        "country_code": "US",
        "line_1": "350 Fifth Avenue",
        "owner_id": "01HXYZ0033ABCDEFGHJKMNPQRS",
        "owner_type": "business",
        "label": "operating_address",
        "created": 1786095703629,
        "updated": 1786095703629
      }
    ],
    "business_officers": [
      {
        "id": "01HXYZ0037ABCDEFGHJKMNPQRS",
        "job_title": "Chief Executive Officer",
        "is_control_person": true,
        "is_beneficial_owner": true,
        "ownership_percentage": 60,
        "business_id": "01HXYZ0033ABCDEFGHJKMNPQRS",
        "created": 1786095703415,
        "updated": 1786095703415,
        "person_id": "01HXYZ0038ABCDEFGHJKMNPQRS",
        "person": {
          "id": "01HXYZ0038ABCDEFGHJKMNPQRS",
          "is_pep": false,
          "first_name": "Alexie",
          "last_name": "Johnson",
          "date_of_birth": "1991-06-15",
          "email": "alexie.johnson3@acmetech.com",
          "nationality": "US",
          "gender": "m",
          "status": "approved",
          "created": 1786095703273,
          "updated": 1786095703273,
          "address": {
            "id": "01HXYZ0039ABCDEFGHJKMNPQRS",
            "city": "New York",
            "state": "New York",
            "postal_code": "10024",
            "country_code": "US",
            "line_1": "210 West 77th Street",
            "owner_id": "01HXYZ0038ABCDEFGHJKMNPQRS",
            "owner_type": "person",
            "created": 1786095703699,
            "updated": 1786095703699
          },
          "identification": {
            "id": "01HXYZ0040ABCDEFGHJKMNPQRS",
            "person_id": "01HXYZ0038ABCDEFGHJKMNPQRS",
            "verification_status": "pending",
            "created": 1786095703838,
            "updated": 1786095767778,
            "document": {
              "type": "international_passport",
              "number": "***4388",
              "issue_date": "2020-01-10",
              "expiry_date": "2030-01-09",
              "issuing_country": "US",
              "verification_status": "pending",
              "document_id": "01HXYZ0041ABCDEFGHJKMNPQRS"
            },
            "proof_of_address": {
              "type": "utility_bill",
              "document_id": "01HXYZ0042ABCDEFGHJKMNPQRS",
              "verification_status": "pending"
            },
            "identity_numbers": [
              {
                "type": "SSN",
                "value": "***6788",
                "verification_status": "pending"
              }
            ]
          }
        }
      }
    ],
    "business_meta": {
      "id": "01HXYZ0043ABCDEFGHJKMNPQRS",
      "business_id": "01HXYZ0033ABCDEFGHJKMNPQRS",
      "meta": {
        "registration_number": "47-7654333",
        "tax_id": "47-1234588",
        "monthly_transaction_value": "100000000000000000000",
        "monthly_payments_count": "10000000",
        "max_transfer_amount": "100000000000000",
        "annual_turnover": "99999999900000000000",
        "customer_types": "Individual",
        "sales_channels": "My own website",
        "funding_source": "Revenue from software subscriptions"
      },
      "created": 1786095703488,
      "updated": 1786095703488
    },
    "documents": [
      {
        "id": "01HXYZ0044ABCDEFGHJKMNPQRS",
        "key": "certificate_of_incorporation",
        "description": "Certificate of Incorporation",
        "urls": {
          "main": "https://files.example.invalid/entity-documents/01HXYZ0032ABCDEFGHJKMNPQRS/1786095721521-mx6a5pz3g48"
        },
        "meta": {
          "file_type": "image/jpeg",
          "content_hash": "c3ecad1620a0cb6caca94ecbce106b37b89dee6f58f63f094d49c9a04ecb6454"
        },
        "created": 1786095721852,
        "updated": 1786095721852
      },
      {
        "id": "01HXYZ0045ABCDEFGHJKMNPQRS",
        "key": "memorandum_of_association",
        "description": "Memorandum Of Association",
        "urls": {
          "main": "https://files.example.invalid/entity-documents/01HXYZ0032ABCDEFGHJKMNPQRS/1786095728921-8gq9ypoua1d"
        },
        "meta": {
          "file_type": "image/jpeg",
          "content_hash": "8e2a4329ce4bcc2ab0e78839f843fe7800bec1730f54015cfd5777b24e295e39"
        },
        "created": 1786095729308,
        "updated": 1786095729308
      },
      {
        "id": "01HXYZ0041ABCDEFGHJKMNPQRS",
        "key": "identity",
        "description": "International Passport",
        "urls": {
          "main": "https://files.example.invalid/entity-documents/01HXYZ0032ABCDEFGHJKMNPQRS/1786095760194-ld8vfpvwlv"
        },
        "meta": {
          "file_type": "image/jpeg",
          "content_hash": "bc1d7e6d12319d45fc8270105a69e2af758feec26f7e034fe85b55623b748b7b"
        },
        "created": 1786095760581,
        "updated": 1786095760581
      },
      {
        "id": "01HXYZ0042ABCDEFGHJKMNPQRS",
        "key": "proof_of_address",
        "description": "Utility Bill",
        "urls": {
          "main": "https://files.example.invalid/entity-documents/01HXYZ0032ABCDEFGHJKMNPQRS/1786095767049-99ay6l70f3h"
        },
        "meta": {
          "file_type": "image/jpeg",
          "content_hash": "f7f7d2d943c1e2d6772197f30c985a61fef7f0f1dbad52e3b6dee0346b0f39c4"
        },
        "created": 1786095767569,
        "updated": 1786095767569
      }
    ],
    "child_entities": []
  }
}

Response fields

string

Always success for a successful request.

string

Human-readable confirmation message.

object

Show data fields

object

The core entity record. See The Entity object.

object

The individual’s personal details. Present only when type is individual.

Show person fields

string

Unique person identifier.

string

Legal first name.

string

Legal last name.

string

Date of birth in YYYY-MM-DD format.

string

Contact email address.

string

ISO 3166-1 alpha-2 country code.

string

m for male, f for female.

boolean

Whether the individual is a politically exposed person.

string

Review state of the person record. One of pending, approved, rejected, or suspended.

string

Phone number including country code.

number

Unix timestamp in milliseconds when the person record was created.

number

Unix timestamp in milliseconds when the person record was last updated.

object

The business’s registered details. Present only when type is business.

Show business fields

string

Unique business record identifier.

string

Full registered legal name of the business.

string

Trading name or DBA, if different from the legal name.

string

Business contact email address.

string

Business phone number including country code.

string

The industry the business operates in.

string

Business website URL.

string

Legal structure. e.g. llc, corporation, partnership, sole_proprietorship.

string

A description of what the business does.

string

Government-issued business registration number.

object

Details of when and where the business was incorporated.

Show incorporation_meta fields

number

Year of incorporation.

number

Month of incorporation. 1–12.

string

ISO 3166-1 alpha-2 country code of incorporation.

string

State or province of incorporation.

number

Unix timestamp in milliseconds when the business record was created.

number

Unix timestamp in milliseconds when the business record was last updated.

array

Addresses associated with this entity.

Show address fields

string

Unique address identifier.

string

Street address line 1.

string

City.

string

State or province.

string

Postal or ZIP code.

string

ISO 3166-1 alpha-2 country code.

string

The ID of the person or business this address belongs to.

string

person or business.

string

The role of this address. e.g. registered_address, operating_address.

number

Unix timestamp in milliseconds when the address was created.

number

Unix timestamp in milliseconds when the address was last updated.

object

The KYC verification record for the individual, once identity documents have been submitted. Present only when type is individual.

Show identification fields

string

Unique identification record identifier.

string

The ID of the person this identification belongs to.

string

Overall verification status. One of pending, approved, rejected, or suspended.

object

The submitted government-issued identity document.

Show document fields

string

Document type. One of international_passport, drivers_license, national_id.

string

Document number. Masked in API responses.

string

Date the document was issued. Format: YYYY-MM-DD.

string

Date the document expires. Format: YYYY-MM-DD.

string

ISO 3166-1 alpha-2 country code of the issuing authority.

string

Name of the authority that issued the document.

string

Verification status of this document.

string

The ID of the uploaded document file. See documents below.

object

The submitted proof of address document.

Show proof_of_address fields

string

One of utility_bill, bank_statement.

string

The ID of the uploaded document file. See documents below.

string

Verification status of this document.

array

National identity numbers supplied for the individual.

Show identity_numbers fields

string

One of BVN, NIN, SSN.

string

The identity number. Masked in API responses.

string

Verification status of this identity number.

number

Unix timestamp in milliseconds when the identification record was created.

number

Unix timestamp in milliseconds when the identification record was last updated.

object

Platform-supplied metadata for the individual. Present only when type is individual.

Show person_meta fields

string

Unique metadata record identifier.

string

The ID of the person this metadata belongs to.

object

Arbitrary key-value metadata supplied when the entity was created or updated.

number

Unix timestamp in milliseconds when the metadata record was created.

number

Unix timestamp in milliseconds when the metadata record was last updated.

object

Platform-supplied metadata for the business. Present only when type is business.

Show business_meta fields

string

Unique metadata record identifier.

string

The ID of the business this metadata belongs to.

object

Arbitrary key-value metadata supplied when the entity was created or updated.

number

Unix timestamp in milliseconds when the metadata record was created.

number

Unix timestamp in milliseconds when the metadata record was last updated.

array

The business’s officers. Present only when type is business.

Show business_officers fields

string

Unique officer record identifier.

string

The officer’s title within the organization.

boolean

Whether this person has significant management control over the business.

boolean

Whether this person owns 25% or more of the business.

number

The officer’s ownership stake. 0–100.

string

The ID of the business this officer belongs to.

string

The ID of the officer’s person record.

object

The officer’s personal details, including their own address and identification. Same shape as Person object.

number

Unix timestamp in milliseconds when the officer record was created.

number

Unix timestamp in milliseconds when the officer record was last updated.

array

Uploaded KYC/KYB documents for this entity.

Show documents fields

string

Unique document identifier.

string

Document category. e.g. identity, proof_of_address, certificate_of_incorporation, memorandum_of_association.

string

Description of the document.

object

Show urls fields

string

URL to the stored document file.

object

Show meta fields

string

MIME type of the uploaded file.

string

Hash of the file contents, used for integrity verification.

number

Unix timestamp in milliseconds when the document was uploaded.

number

Unix timestamp in milliseconds when the document was last updated.

array

Entities created with this entity as parent_entity. Empty if this entity has no children.

Entity statuses

Status	Description
`incomplete`	Entity created but not submitted.
`pending`	Entity submitted, awaiting review.
`approved`	KYC/KYB passed. Accounts can be created for this entity.
`rejected`	Review failed. The entity cannot proceed. Check the rejection reason returned by the webhook.
`failed`	Verification failed.
`suspended`	Account access temporarily restricted. Contact support to resolve.

​The Entity object

​Create an individual entity

Request fields

​Response

​Update an individual entity

​Path parameters

​Request parameters

​Sample Response

​Response fields

​Create a business entity

​Request fields

​Person object

​Response

​Upload a KYC document

​Request parameters

​Response

​Submit for onboarding review

​Request parameters

​Response

​Update a business entity

​Path parameters

​Request parameters

​Response fields

​Get an entity

​Path parameters

​Response

​Response fields

​Entity statuses

The Entity object

Create an individual entity

Response

Update an individual entity

Path parameters

Request parameters

Sample Response

Response fields

Create a business entity

Request fields

Person object

Response

Upload a KYC document

Request parameters

Response

Submit for onboarding review

Request parameters

Response

Update a business entity

Path parameters

Request parameters

Response fields

Get an entity

Path parameters

Response

Response fields

Entity statuses