> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuvion.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Entities

> Create and manage the individuals and businesses that hold accounts on your platform.

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

<ResponseField name="id" type="string">
  Unique entity identifier.
</ResponseField>

<ResponseField name="type" type="string">
  `individual` or `business`.
</ResponseField>

<ResponseField name="status" type="string">
  Review state. One of `pending`, `approved`, `rejected`, or `suspended`. See [Entity statuses](#entity-statuses) below.
</ResponseField>

<ResponseField name="profile" type="object">
  Identity details. Shape depends on `type`.

  <Expandable title="Individual profile fields">
    <ResponseField name="first_name" type="string">
      Legal first name.
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Legal last name.
    </ResponseField>

    <ResponseField name="email" type="string">
      Contact email address.
    </ResponseField>

    <ResponseField name="date_of_birth" type="string">
      Date of birth in `YYYY-MM-DD` format.
    </ResponseField>

    <ResponseField name="country_of_residence" type="string">
      ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`).
    </ResponseField>
  </Expandable>

  <Expandable title="Business profile fields">
    <ResponseField name="legal_name" type="string">
      Full registered legal name of the business.
    </ResponseField>

    <ResponseField name="email" type="string">
      Business contact email address.
    </ResponseField>

    <ResponseField name="business_type" type="string">
      Legal structure. One of `llc`, `corporation`, `partnership`, or `sole_proprietorship`.
    </ResponseField>

    <ResponseField name="country_of_incorporation" type="string">
      ISO 3166-1 alpha-2 country code where the business is incorporated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Set of key-value pairs for storing additional platform-defined data.
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp in milliseconds when the entity was created.
</ResponseField>

<ResponseField name="updated" type="number">
  Unix timestamp in milliseconds when the entity was last updated.
</ResponseField>

```json Example theme={null}
{
  "id": "01HXYZ1234ABCD",
  "type": "individual",
  "status": "pending",
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "date_of_birth": "1990-06-15",
    "country_of_residence": "US"
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}
```

***

## Create an individual entity

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

<CodeGroup>
  ```bash curl theme={null}
  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": "1990-04-12",
        "email": "alex.johnson@example.com",
        "nationality": "US",
        "gender": "m",
        "phonenumber": "+12125550198",
        "bvn": "23487892834",
        "nin": "25856743645",
        "ssn": "123-45-6789"
      },
      "address": {
        "line_1": "210 West 77th Street",
        "line_2": "Apt 4B",
        "line_3": "Suite 5C",
        "city": "New York",
        "state": "New York",
        "postal_code": "10024",
        "country_code": "US"
      },
      "identification": {
        "document": {
          "type": "international_passport",
          "number": "P123456789",
          "issue_date": "2020-01-10",
          "expiry_date": "2030-01-09",
          "issuing_country": "US",
          "issuing_authority": "US Department of State",
          "document_id": "01HXYZ1234ABCD",
          "type_specific": {
            "id_subtype": "SSN"
          }
        },
        "proof_of_address": {
          "type": "utility_bill",
          "document_id": "01HXYZ5678EFGH"
        }
      },
      "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",
      }
    }'
  ```
</CodeGroup>

##### Request fields

<ParamField body="name" type="string" required>
  A display name for the entity. 1–255 characters.
</ParamField>

<ParamField body="person" type="object" required>
  Personal details for the individual.

  <Expandable title="person fields">
    <ParamField body="first_name" type="string" required>
      1–100 characters.
    </ParamField>

    <ParamField body="last_name" type="string" required>
      1–100 characters.
    </ParamField>

    <ParamField body="middle_name" type="string">
      Max 100 characters.
    </ParamField>

    <ParamField body="date_of_birth" type="string" required>
      Format: `YYYY-MM-DD`.
    </ParamField>

    <ParamField body="email" type="string" required>
      Valid email address.
    </ParamField>

    <ParamField body="nationality" type="string" required>
      ISO 3166-1 alpha-2 country code. e.g. `US`, `GB`, `CA`.
    </ParamField>

    <ParamField body="gender" type="string" required>
      `m` for male, `f` for female.
    </ParamField>

    <ParamField body="phonenumber" type="string" required>
      Phone number including country code. 10–14 characters.
    </ParamField>

    <ParamField body="bvn" type="string">
      Bank Verification Number (BVN) required for Nigerian nationals.
    </ParamField>

    <ParamField body="nin" type="string">
      National Identity Number (NIN) required for Nigerian nationals.
    </ParamField>

    <ParamField body="ssn" type="string">
      Social Security Number (SSN) required for U.S. nationals.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="address" type="object">
  Residential address of the individual.

  <Expandable title="address fields">
    <ParamField body="line_1" type="string" required>Street address line 1. 1–255 characters.</ParamField>
    <ParamField body="line_2" type="string">Street address line 2. Max 255 characters.</ParamField>
    <ParamField body="line_3" type="string">Street address line 3. Max 255 characters.</ParamField>
    <ParamField body="city" type="string" required>City. 1–100 characters.</ParamField>
    <ParamField body="state" type="string" required>State or province. 1–100 characters.</ParamField>
    <ParamField body="postal_code" type="string" required>Postal or ZIP code. 1–20 characters.</ParamField>
    <ParamField body="country_code" type="string" required>ISO 3166-1 alpha-2 country code. e.g. `US`, `GB`, `CA`.</ParamField>
    <ParamField body="meta" type="object">Additional address metadata.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="identification" type="object">
  Identity and address verification documents.

  <Expandable title="identification fields">
    <ParamField body="document" type="object">
      Government-issued identity document.

      <Expandable title="document fields">
        <ParamField body="type" type="string" required>
          Document type. One of `international_passport`, `drivers_license`, `national_id`.
        </ParamField>

        <ParamField body="number" type="string" required>
          Document number.
        </ParamField>

        <ParamField body="issue_date" type="string">
          Date the document was issued. Format: `YYYY-MM-DD`.
        </ParamField>

        <ParamField body="expiry_date" type="string">
          Date the document expires. Format: `YYYY-MM-DD`.
        </ParamField>

        <ParamField body="issuing_country" type="string">
          ISO 3166-1 alpha-2 country code of the issuing authority.
        </ParamField>

        <ParamField body="issuing_authority" type="string">
          Name of the authority that issued the document.
        </ParamField>

        <ParamField body="type_specific" type="object">
          Additional fields for country-specific document types.

          <Expandable title="type_specific fields">
            <ParamField body="id_subtype" type="string">
              Subtype for national ID documents. One of `BVN`, `SSN`, `NIN`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="proof_of_address" type="object">
      Address verification document.

      <Expandable title="proof_of_address fields">
        <ParamField body="type" type="string" required>
          One of `utility_bill`, `bank_statement`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="business" type="object">
  Business context for the individual, if applicable (e.g. a sole trader or freelancer).

  <Expandable title="business fields">
    <ParamField body="name" type="string" required>Trading name. 1–100 characters.</ParamField>
    <ParamField body="description" type="string" required>Description of the business activity. 1–200 characters.</ParamField>
    <ParamField body="category_code" type="string" required>Business category code. 1–100 characters.</ParamField>
    <ParamField body="sub_category_code" type="string">Business sub-category code. 1–100 characters.</ParamField>
    <ParamField body="website" type="string">Business website URL.</ParamField>
    <ParamField body="liveness_report_url" type="string">URL of a liveness or biometric report for this individual.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="meta" type="object">
  Additional compliance and risk metadata.

  <Expandable title="meta fields">
    <ParamField body="tax_id" type="string">Tax identification number.</ParamField>
    <ParamField body="monthly_payments_count" type="string">Expected number of monthly payments.</ParamField>
    <ParamField body="monthly_transaction_value" type="string">Expected monthly transaction volume.</ParamField>
    <ParamField body="max_transfer_amount" type="string">Maximum single transfer amount.</ParamField>
    <ParamField body="annual_turnover" type="string">Estimated annual income or revenue.</ParamField>
    <ParamField body="customer_types" type="string">Description of the individual's customer base, if applicable.</ParamField>
    <ParamField body="funding_source" type="string">Primary source of funds. e.g. `salary`, `business_income`, `investments`.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="parent_entity" type="string">
  The ID of a parent entity, if this individual is associated with a business entity. 26-character ULID.
</ParamField>

<ParamField body="parent_relationship" type="string">
  Description of the relationship to the parent entity. 1–100 characters.
</ParamField>

### Response

Returns the created entity object with `status: "pending"`.

```json Response theme={null}
{
  "id": "01HXYZ1234ABCD",
  "type": "individual",
  "status": "pending",
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "date_of_birth": "1990-06-15",
    "country_of_residence": "US"
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}
```

<Note>
  The response includes a `person_id` field used to associate KYC documents in the next step. See [Entities guide](/core-concepts/entities) for the full onboarding flow.
</Note>

***

## Update an individual entity

Updates the profile of an existing individual entity.

<CodeGroup>
  ```bash curl -X PATCH https://api.nuvion.dev/individual-entities/:entityId \ theme={null}
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Jane_Smith",
      "person": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "date_of_birth": "1990-06-15",
      "nationality": "US",
      "gender": "F",
      "phonenumber": "+1234567890",
      }
    }'
  ```
</CodeGroup>

### Request parameters

<ParamField body="name" type="string">
  The name of the individual entity.
</ParamField>

<ParamField body="person" type="object">
  The profile details of the individual entity.

  <Expandable title="person fields">
    <ParamField body="first_name" type="string">
      Legal first name of the individual.
    </ParamField>

    <ParamField body="last_name" type="string">
      Legal last name of the individual.
    </ParamField>

    <ParamField body="email" type="string">
      Contact email address. Must be a valid email format.
    </ParamField>

    <ParamField body="date_of_birth" type="string">
      Date of birth in `YYYY-MM-DD` format (e.g. `1990-06-15`).
    </ParamField>

    <ParamField body="nationality" type="string">
      ISO 3166-1 alpha-2 country code for the individual's nationality (e.g. `US`).
    </ParamField>

    <ParamField body="gender" type="string">
      The individual's gender. One of `M`, `F`, or `Other`.
    </ParamField>

    <ParamField body="phonenumber" type="string">
      The individual's phone number.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="address" type="object">
  The address of the individual entity.

  <Expandable title="address fields">
    <ParamField body="line_1" type="string">
      Street address line 1.
    </ParamField>

    <ParamField body="line_2" type="string">
      Street address line 2.
    </ParamField>

    <ParamField body="line_3" type="string">
      Street address line 3.
    </ParamField>

    <ParamField body="metal_line" type="string">
      Additional address metadata.
    </ParamField>

    <ParamField body="city" type="string">
      City.
    </ParamField>

    <ParamField body="state" type="string">
      State/province/region.
    </ParamField>

    <ParamField body="postal_code" type="string">
      Postal or ZIP code.
    </ParamField>

    <ParamField body="country_code" type="string">
      ISO 3166-1 alpha-2 country code (e.g. `US`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="business" type="object">
  <Expandable title="business fields">
    <ParamField body="website" type="string">
      Full registered legal name of the business.
    </ParamField>

    <ParamField body="name" type="string">
      Business contact name
    </ParamField>

    <ParamField body="liveness_report_url" type="string">
      Business liveness report url.
    </ParamField>

    <ParamField body="description" type="string">
      Business description.
    </ParamField>

    <ParamField body="category_code" type="string">
      The business's industry category code (e.g. `5812` for restaurants).
    </ParamField>

    <ParamField body="sub_category_code" type="string">
      The business's industry sub-category code (e.g. `581208` for fast food restaurants).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="identification" type="object">
  The identification details of the individual entity.

  <Expandable title="identification fields">
    <ParamField body="document" type="object">
      The identification document details.

      <Expandable title="document fields">
        <ParamField body="type" type="string">
          The type of identification document. One of `passport`, `driver_license`, or `national_id`.
        </ParamField>

        <ParamField body="number" type="string">
          The identification document number.
        </ParamField>

        <ParamField body="issue_date" type="string">
          Issue date of the identification document in `YYYY-MM-DD` format (e.g. `2020-01-01`).
        </ParamField>

        <ParamField body="expiry_date" type="string">
          Expiry date of the identification document in `YYYY-MM-DD` format (e.g. `2030-12-31`).
        </ParamField>

        <ParamField body="issuing_country" type="string">
          ISO 3166-1 alpha-2 country code where the identification document was issued (e.g. `US`).
        </ParamField>

        <ParamField body="issuing_authority" type="string">
          The authority that issued the identification document.
        </ParamField>

        <ParamField body="document_id" type="string">
          The ID of the uploaded identification document returned by the document upload endpoint.
        </ParamField>

        <ParamField body="type_specific" type="object">
          Additional fields specific to the type of identification document.

          <Expandable title="type_specific fields">
            <Paramfiel body="id_subtype" type="string">
              The subtype of the document (SSN, BVN,NIN).
            </Paramfiel>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="proof_of_address" type="object">
      The proof of address document details.

      <Expandable title="proof_of_address fields">
        <ParamField body="type" type="string">
          The utility bill document type (utility|Bank statement).
        </ParamField>

        <ParamField body="document_id" type="string">
          The ID of the uploaded proof of address document returned by the document upload endpoint.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="parent_entity" type="string">
  The parent entity. This links the individual to the to the parent entity for hierarchical relationship.
</ParamField>

<ParamField body="parent_relationship" type="string">
  The relationship of the individual to the parent entity. This describes the relationship of the individual to the parent entity (e.g. director, owner, etc.).
</ParamField>

### Sample Response

<CodeGroup>
  ```json theme={null}
  {
      "message": "Individual entity updated successfully",
      "status": "success",
      "data": {
          "changes_applied": {
              "entity_fields": [],
              "person_fields": [],
              "address_fields": [],
              "identification_fields": []
          },
          "address": {
              "id": "01K42STB8B1PF6M89S8TZM3DMF",
              "line_1": "456 Home Street",
              "line_2": "",
              "city": "London",
              "state": "BRY",
              "postal_code": "EC1A 1BB",
              "country_code": "NG",
              "owner_id": "01K42STB61BVP189XE0V0HFT1W",
              "owner_type": "person",
              "created": 1756735810827,
              "updated": 1767137386937
          },
          "entity": {
              "id": "01K42STB8BJPG83AHR297586C2",
              "type": "individual",
              "status": "approved",
              "name": "Alycia Bernhard",
              "is_root": false,
              "user_id": "01K42STB6298K78CZQZ7JA1EZ9",
              "creation_context": "user",
              "created": 1756735810827,
              "updated": 1770112256131
          },
          "person": {
              "id": "01K42STB61BVP189XE0V0HFT1W",
              "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": "01KDRWS7NA4ZVFCC7HJ4KZK6DG",
              "person_id": "01K42STB61BVP189XE0V0HFT1W",
              "verification_status": "pending",
              "created": 1767140794026,
              "updated": 1767140793956,
              "proof_of_address": {
                  "type": "utility_bill",
                  "document_id": "01KDRWS7GV2NZ66R71E4AC4WYS",
                  "verification_status": "pending"
              }
          }
      }
  }
  ```
</CodeGroup>

### Response fields

<ParamField body="message" type="string">
  A message describing the result of the update operation.
</ParamField>

<ParamField body="status" type="string">
  The status of the update operation.
</ParamField>

<ParamField body="data" type="object">
  The updated entity data.

  <Expandable title="data">
    <ParamField body="changes_applied" type="object">
      The specific fields that were updated in the entity, person, address, and identification objects.
    </ParamField>

    <ParamField body="address" type="array">
      The updated address object for the individual entity.
    </ParamField>

    <ParamField body="entity" type="array">
      The updated entity object for the individual entity.
    </ParamField>

    <ParamField body="person" type="array">
      The updated person object for the individual entity.
    </ParamField>

    <ParamField body="identification" type="array">
      The updated identification object for the individual entity.
    </ParamField>

    <ParamField body="address" type="object">
      The updated address details of the individual entity.

      <Expandable title="address fields">
        <ParamField body="line_1" type="string">
          Street address line 1.
        </ParamField>

        <ParamField body="line_2" type="string">
          Street address line 2.
        </ParamField>

        <ParamField body="line_3" type="string">
          Street address line 3.
        </ParamField>

        <ParamField body="meta" type="string">
          Additional address metadata.
        </ParamField>

        <ParamField body="city" type="string">
          City.
        </ParamField>

        <ParamField body="state" type="string">
          State/province/region.
        </ParamField>

        <ParamField body="postal_code" type="string">
          Postal or ZIP code.
        </ParamField>

        <ParamField body="country_code" type="string">
          ISO 3166-1 alpha-2 country code (e.g. `US`).
        </ParamField>

        <ParamField body="owner_id" type="string">
          The ID of the owner of the address (person or business).
        </ParamField>

        <ParamField body="owner_type" type="string">
          The type of the owner of the address (person or business).
        </ParamField>

        <ParamField body="created" type="number">
          Unix timestamp in milliseconds when the address was created.
        </ParamField>

        <ParamField body="updated" type="number">
          Unix timestamp in milliseconds when the address was last updated.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="entity" type="object">
      The updated entity details of the individual entity.

      <Expandable title="entity fields">
        <ParamField body="id" type="string">
          Unique entity identifier. Prefix: `ent_`.
        </ParamField>

        <ParamField body="type" type="string">
          `individual` or `business`.
        </ParamField>

        <ParamField body="status" type="string">
          Review state. One of `pending`, `approved`, `rejected`, or `suspended`.
        </ParamField>

        <ParamField body="name" type="string">
          The name of the individual entity.
        </ParamField>

        <ParamField body="is_root" type="boolean">
          Indicates if this entity is a root entity in a hierarchical relationship.
        </ParamField>

        <ParamField body="user_id" type="string">
          The ID of the user associated with this entity, if applicable.
        </ParamField>

        <ParamField body="creation_context" type="string">
          The context in which the entity was created (e.g. "user", "admin", "api").
        </ParamField>

        <ParamField body="created" type="number">
          Unix timestamp in milliseconds when the entity was created.
        </ParamField>

        <ParamField body="updated" type="number">
          Unix timestamp in milliseconds when the entity was last updated.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="person" type="object">
      The updated person details of the individual entity.

      <Expandable title="person fields">
        <ParamField body="first_name" type="string">
          Legal first name of the individual.
        </ParamField>

        <ParamField body="last_name" type="string">
          Legal last name of the individual.
        </ParamField>

        <ParamField body="middle_name" type="string">
          Middle name of the individual.
        </ParamField>

        <ParamField body="date_of_birth" type="string">
          Date of birth in `YYYY-MM-DD` format (e.g. `1990-06-15`).
        </ParamField>

        <ParamField body="email" type="string">
          Contact email address. Must be a valid email format.
        </ParamField>

        <ParamField body="nationality" type="string">
          ISO 3166-1 alpha-2 country code for the individual's nationality (e.g. `US`).
        </ParamField>

        <ParamField body="gender" type="string">
          The individual's gender. One of `M`, `F`, or `Other`.
        </ParamField>

        <ParamField body="is_pep" type="boolean">
          Indicates if the individual is a politically exposed person (PEP).
        </ParamField>

        <ParamField body="status" type="string">
          The review status of the individual's profile. One of `pending`, `approved`, `rejected`, or `suspended`.
        </ParamField>

        <ParamField body="phonenumber" type="string">
          The individual's phone number.
        </ParamField>

        <ParamField body="created" type="number">
          Unix timestamp in milliseconds when the person profile was created.
        </ParamField>

        <ParamField body="updated" type="number">
          Unix timestamp in milliseconds when the person profile was last updated.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="identification" type="object">
      The updated identification details of the individual entity.

      <Expandable title="identification fields">
        <ParamField body="verification_status" type="string">
          The overall verification status of the individual's identification. One of `pending`, `approved`, `rejected`, or `suspended`.
        </ParamField>

        <ParamField body="created" type="number">
          Unix timestamp in milliseconds when the identification details were created.
        </ParamField>

        <ParamField body="updated" type="number">
          Unix timestamp in milliseconds when the identification details were last updated.
        </ParamField>

        <ParamField body="proof_of_address" type="object">
          The updated proof of address document details.

          <Expandable title="proof_of_address fields">
            <ParamField body="type" type="string">
              The utility bill document type (utility|Bank statement).
            </ParamField>

            <ParamField body="document_id" type="string">
              The ID of the uploaded proof of address document returned by the document upload endpoint.
            </ParamField>

            <ParamField body="verification_status" type="string">
              The verification status of the proof of address document. One of `pending`, `approved`, `rejected`, or `suspended`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Create a business entity

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

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/business-entities \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Acme Technologies Ltd",
      "business": {
        "legal_name": "Acme Technologies Limited",
        "trade_name": "Acme Tech",
        "industry": "Technology",
        "email": "finance@acmetech.com",
        "website": "https://acmetech.com",
        "type": "llc",
        "description": "A B2B SaaS platform for logistics management.",
        "registration_number": "EIN-47-1234567",
        "phonenumber": "+12125550100",
        "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": "EIN-47-1234567",
        "tax_id": "TAX-47-1234567",
        "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"
      }
    }'
  ```
</CodeGroup>

#### Request fields

<ResponseField name="name" type="string" required>
  A display name for the entity. 1–255 characters.
</ResponseField>

<ResponseField name="business" type="object" required>
  Core business information.

  <Expandable title="business fields">
    <ResponseField name="legal_name" type="string" required>
      The entity's registered legal name. 1–255 characters.
    </ResponseField>

    <ResponseField name="trade_name" type="string">
      Trading name or DBA, if different from the legal name. Max 255 characters.
    </ResponseField>

    <ResponseField name="industry" type="string" required>
      The industry the business operates in. 1–100 characters.
    </ResponseField>

    <ResponseField name="email" type="string" required>
      Business contact email address.
    </ResponseField>

    <ResponseField name="website" type="string">
      Business website URL.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Legal structure of the business. e.g. `llc`, `corporation`, `partnership`, `sole_proprietorship`.
    </ResponseField>

    <ResponseField name="description" type="string" required>
      A description of what the business does. 1–1000 characters.
    </ResponseField>

    <ResponseField name="registration_number" type="string" required>
      Government-issued business registration number. 1–255 characters.
    </ResponseField>

    <ResponseField name="phonenumber" type="string">
      Business phone number including country code. 10–14 characters.
    </ResponseField>

    <ResponseField name="incorporation_meta" type="object" required>
      Details of when and where the business was incorporated.

      <Expandable title="incorporation_meta fields">
        <ResponseField name="year" type="number" required>
          Year of incorporation.
        </ResponseField>

        <ResponseField name="month" type="number" required>
          Month of incorporation. 1–12.
        </ResponseField>

        <ResponseField name="country" type="string" required>
          ISO 3166-1 alpha-2 country code of incorporation. e.g. `NG`, `US`.
        </ResponseField>

        <ResponseField name="state" type="string" required>
          State or province of incorporation. 1–100 characters.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="address" type="object">
  Registered address of the business.

  <Expandable title="address fields">
    <ResponseField name="line_1" type="string" required>
      Street address line 1. 1–255 characters.
    </ResponseField>

    <ResponseField name="line_2" type="string">
      Street address line 2. Max 255 characters.
    </ResponseField>

    <ResponseField name="line_3" type="string">
      Street address line 3. Max 255 characters.
    </ResponseField>

    <ResponseField name="city" type="string" required>
      City. 1–100 characters.
    </ResponseField>

    <ResponseField name="state" type="string" required>
      State or province. 1–100 characters.
    </ResponseField>

    <ResponseField name="postal_code" type="string" required>
      Postal or ZIP code. 1–20 characters.
    </ResponseField>

    <ResponseField name="country_code" type="string" required>
      ISO 3166-1 alpha-2 country code. e.g. `NG`, `US`, `GB`.
    </ResponseField>

    <ResponseField name="meta" type="object">
      Additional address metadata.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="operating_address" type="object">
  The address where the business physically operates, if different from the registered address. Same structure as `address`.
</ResponseField>

<ResponseField name="business_officers" type="array">
  The individuals associated with the business. At least one officer is required.

  <Expandable title="business_officers fields">
    <ResponseField name="job_title" type="string" required>
      The officer's title within the organization. 1–100 characters.
    </ResponseField>

    <ResponseField name="is_control_person" type="boolean" required>
      Whether this person has significant management control over the business.
    </ResponseField>

    <ResponseField name="is_beneficial_owner" type="boolean" required>
      Whether this person owns 25% or more of the business.
    </ResponseField>

    <ResponseField name="ownership_percentage" type="number" required>
      The officer's ownership stake. 0–100.
    </ResponseField>

    <ResponseField name="person" type="object">
      Personal details for the officer. See [Person object](#person-object) below.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Additional compliance and business metadata.

  <Expandable title="meta fields">
    <ResponseField name="registration_number" type="string">
      Government-issued registration number, if not provided in the `business` object.
    </ResponseField>

    <ResponseField name="tax_id" type="string">
      Tax identification number.
    </ResponseField>

    <ResponseField name="annual_turnover" type="string">
      Estimated annual revenue.
    </ResponseField>

    <ResponseField name="monthly_transaction_value" type="string">
      Expected monthly transaction volume.
    </ResponseField>

    <ResponseField name="monthly_payments_count" type="string">
      Expected number of monthly payments.
    </ResponseField>

    <ResponseField name="max_transfer_amount" type="string">
      Maximum single transfer amount.
    </ResponseField>

    <ResponseField name="customer_types" type="string">
      Description of the business's customer base.
    </ResponseField>

    <ResponseField name="sales_channels" type="string">
      Channels through which the business sells (e.g. online, in-person).
    </ResponseField>

    <ResponseField name="funding_source" type="string">
      Primary source of funds for the business.
    </ResponseField>

    <ResponseField name="liveness_check_id" type="string">
      Reference ID from a liveness or biometric check.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="parent_entity" type="string">
  The ID of a parent entity, if this entity is a subsidiary or related entity. The `parent_relationship` field is set by Nuvion based on the relationship type.
</ResponseField>

***

#### Person object

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

<ResponseField name="first_name" type="string" required>
  1–100 characters.
</ResponseField>

<ResponseField name="last_name" type="string" required>
  1–100 characters.
</ResponseField>

<ResponseField name="middle_name" type="string">
  Max 100 characters.
</ResponseField>

<ResponseField name="date_of_birth" type="string" required>
  Format: `YYYY-MM-DD`.
</ResponseField>

<ResponseField name="email" type="string" required>
  Valid email address.
</ResponseField>

<ResponseField name="nationality" type="string" required>
  ISO 3166-1 alpha-2 country code. e.g. `NG`, `GH`, `US`.
</ResponseField>

<ResponseField name="gender" type="string" required>
  `m` for male, `f` for female.
</ResponseField>

<ResponseField name="phonenumber" type="string" required>
  Phone number including country code. 10–14 characters.
</ResponseField>

<ResponseField name="bvn" type="string">
  Bank Verification Number (BVN) required for Nigerian nationals.
</ResponseField>

<ResponseField name="nin" type="string">
  National Identity Number (NIN) required for Nigerian nationals.
</ResponseField>

<ResponseField name="ssn" type="string">
  Social Security Number (SSN) required for U.S. nationals.
</ResponseField>

<ResponseField name="identification" type="object">
  Identity verification documents for this person.

  <Expandable title="identification fields">
    <ResponseField name="document" type="object" required>
      Government-issued identity document. Must be from a non-sanctioned country.

      <Expandable title="document fields">
        <ResponseField name="type" type="string" required>
          Document type. One of `international_passport`, `drivers_license`, `national_id`.
        </ResponseField>

        <ResponseField name="number" type="string" required>
          Document number.
        </ResponseField>

        <ResponseField name="issue_date" type="string">
          Date the document was issued. Format: `YYYY-MM-DD`.
        </ResponseField>

        <ResponseField name="expiry_date" type="string">
          Date the document expires. Format: `YYYY-MM-DD`.
        </ResponseField>

        <ResponseField name="issuing_country" type="string">
          ISO 3166-1 alpha-2 country code of the issuing authority.
        </ResponseField>

        <ResponseField name="issuing_authority" type="string">
          Name of the authority that issued the document.
        </ResponseField>

        <ResponseField name="type_specific" type="object">
          Additional fields for country-specific document types.

          <Expandable title="type_specific fields">
            <ResponseField name="id_subtype" type="string">
              Subtype for national ID documents. One of `BVN`, `SSN`, `NIN`.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="proof_of_address" type="object">
      Address verification document.

      <Expandable title="proof_of_address fields">
        <ResponseField name="type" type="string" required>
          One of `utility_bill`, `bank_statement`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="address" type="object">
  Residential address of this person. Same structure as the business `address` object.
</ResponseField>

### Response

Returns the created entity object with `type: "business"` and `status: "pending"`.

```json Response theme={null}
{
  "id": "01HXYZ7890EFGH",
  "type": "business",
  "status": "pending",
  "profile": {
    "legal_name": "Acme Corp Ltd",
    "email": "accounts@acmecorp.com",
    "business_type": "llc",
    "country_of_incorporation": "US"
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}
```

***

## Upload a KYC document

Upload identity verification documents for an individual entity. Two documents are required before submitting for onboarding review: One Government Issued ID/Proof of Identity (Passport, driver's license, national ID) and one proof of address (Utility bill, bank statement, or government correspondence).

Documents must be passed as base64-encoded strings.

<CodeGroup>
  ```bash Identity document theme={null}
  curl -X POST https://api.nuvion.dev/documents \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entity_id": "01HXYZ1234ABCD",
      "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": "per_01HXYZ1234ABCD"
      }
    }'
  ```

  ```bash Proof of address theme={null}
  curl -X POST https://api.nuvion.dev/documents \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entity_id": "01HXYZ1234ABCD",
      "key": "address",
      "description": "Utility bill for Alex Johnson",
      "file": "base64_encoded_content_here",
      "meta": {
        "file_type": "application/pdf"
      },
      "link_to_identity": {
        "person_id": "01HXYZ1234ABCD"
      }
    }'
  ```
</CodeGroup>

### Request parameters

<ParamField body="key" type="string" required>
  Document type. `identity` for a government-issued photo ID (passport, driver's license, national ID); `address` for proof of address dated within the last 3 months (utility bill, bank statement).
</ParamField>

<ParamField body="link_to_identity[person_id]" type="string" required>
  The `person_id` returned in the response when the individual entity was created.
</ParamField>

<ParamField body="file" type="file" required>
  The document file. Accepted formats: PDF, JPG, PNG. Maximum file size: 10 MB.
</ParamField>

### Response

```json Response theme={null}
{
  "id": "01HXYZ3456MNOP",
  "key": "identity",
  "status": "uploaded",
  "created": 1735725600000
}
```

<Note>
  Upload two documents per individual entity: one with `key: identity` and one with `key: address`. Both are required before calling the onboarding submission endpoint.
</Note>

***

## Submit for onboarding review

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.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/onboarding-submissions \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entity_id": "01HXYZ1234ABCD"
    }'
  ```
</CodeGroup>

### Request parameters

<ParamField body="entity_id" type="string" required>
  The ID of the entity to submit for review.
</ParamField>

### 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`.

```json Response theme={null}
{
  "id": "01HXYZ1234ABCD",
  "type": "individual",
  "status": "pending",
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "date_of_birth": "1990-06-15",
    "country_of_residence": "US"
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}
```

## Update a business entity

Updates the profile of an existing business entity.

<CodeGroup>
  ```bash curl -X PATCH https://api.nuvion.dev/business-entities/:entityId \ theme={null}
    -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": "passport",
                "number": "123456789",
                "issue_date": "2020-01-01",
                "expiry_date": "2030-12-31",
                "issuing_country": "US",
                "issuing_authority": "US Department of State",
                "document_id": "doc_01HXYZ3456MNOP"
                "type_specific": {
                  "id_subtype": "SSN|BVN|NIN"
                }
              }
              "Proof_of_address": {
                "type": "utility|bank_statement",
                "document_id": "doc_01HXYZ3456MNOP"
              }
            },
            "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_channel": "" //string - the primary sales channel for the business (e.g. "online", "in-person", "both") to provide additional context for KYB review
          "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_entity": "", //string - the parent entity ID to link to for hierarchical relationship
        "parent_relationship": "" //string - the relationship of the business to the parent entity (
    }'
  ```
</CodeGroup>

## Request Parameters

<ParamField body="name" type="string">
  The name of the business entity.
</ParamField>

<ParamField body="business" type="object">
  The profile details of the business entity.

  <Expandable title="business fields">
    <ParamField body="legal_name" type="string">
      Full registered legal name of the business as it appears on incorporation documents.
    </ParamField>

    <ParamField body="trade_name" type="string">
      The name the business operates under if different from `legal_name` (DBA).
    </ParamField>

    <ParamField body="website" type="string">
      The business's website URL.
    </ParamField>

    <ParamField body="description" type="string">
      A description of the business.
    </ParamField>

    <ParamField body="type" type="string">
      Legal structure of the business. One of `llc`, `corporation`, `partnership`, or `sole_proprietorship`.
    </ParamField>

    <ParamField body="phonenumber" type="string">
      The business's phone number.
    </ParamField>

    <ParamField body="email" type="string">
      The business's contact email address.
    </ParamField>

    <ParamField body="registration_number" type="string">
      The business's registration number from the government authority where it is incorporated.
    </ParamField>

    <ParamField body="incorporation_meta" type="object">
      Additional details about the business's incorporation.

      <Expandable title="incorporation_meta fields">
        <ParamField body="year" type="string">
          The year the business was incorporated (e.g. "2020").
        </ParamField>

        <ParamField body="month" type="string">
          The month the business was incorporated (e.g. "01" for January).
        </ParamField>

        <ParamField body="country" type="string">
          ISO 3166-1 alpha-2 country code where the business is incorporated (e.g. "US").
        </ParamField>

        <ParamField body="state" type="string">
          State or province where the business is incorporated, if applicable (e.g. "NY").
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="address" type="object">
  The registered address of the business.

  <Expandable title="address fields">
    <ParamField body="line_1" type="string">
      Street address line 1.
    </ParamField>

    <ParamField body="line_2" type="string">
      Street address line 2.
    </ParamField>

    <ParamField body="line_3" type="string">
      Street address line 3.
    </ParamField>

    <ParamField body="meta" type="string">
      Additional address metadata.
    </ParamField>

    <ParamField body="city" type="string">
      City.
    </ParamField>

    <ParamField body="state" type="string">
      State or province.
    </ParamField>

    <ParamField body="postal_code" type="string">
      Postal or ZIP code.
    </ParamField>

    <ParamField body="country_code" type="string">
      ISO 3166-1 alpha-2 country code (e.g. `US`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="operating_address" type="object">
  The operating address of the business if different from the registered address.

  <Expandable title="operating_address fields">
    <ParamField body="line_1" type="string">
      Street address line 1.
    </ParamField>

    <ParamField body="line_2" type="string">
      Street address line 2.
    </ParamField>

    <ParamField body="line_3" type="string">
      Street address line 3.
    </ParamField>

    <ParamField body="meta" type="string">
      Additional address metadata.
    </ParamField>

    <ParamField body="city" type="string">
      City.
    </ParamField>

    <ParamField body="state" type="string">
      State or province.
    </ParamField>

    <ParamField body="postal_code" type="string">
      Postal or ZIP code.
    </ParamField>

    <ParamField body="country_code" type="string">
      ISO 3166-1 alpha-2 country code (e.g. `US`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="business_officers" type="array">
  A list of the business's officers and their details.

  <Expandable title="business_officers fields">
    <ParamField body="id" type="string">
      The ID of the business officer. Required when updating an existing officer, not needed when adding a new officer.
    </ParamField>

    <ParamField body="person_id" type="string">
      The ID of the individual entity associated with this officer. Required when adding a new officer to link to an existing individual entity.
    </ParamField>

    <ParamField body="job_title" type="string">
      The officer's job title (e.g. "CEO", "Director", etc.).
    </ParamField>

    <ParamField body="is_control_person" type="boolean">
      Whether the officer is a control person for the business.
    </ParamField>

    <ParamField body="is_beneficial_owner" type="boolean">
      Whether the officer is a beneficial owner of the business.
    </ParamField>

    <ParamField body="ownership_percentage" type="number">
      The percentage of ownership the officer has in the business, if applicable.
    </ParamField>

    <ParamField body="action" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="meta" type="object">
  Additional metadata about the business entity to provide more context for KYB review.

  <Expandable title="meta fields">
    <ParamField body="registration_number" type="string">
      The business's registration number from the government authority where it is incorporated.
    </ParamField>

    <ParamField body="tax_id" type="string">
      The business's tax identification number.
    </ParamField>

    <ParamField body="liveness_check_id" type="string">
      The ID of a liveness check report to link to the business entity for KYB review.
    </ParamField>

    <ParamField body="monthly_payment_count" type="number">
      The number of payments processed by the business in the past month to provide additional context for KYB review.
    </ParamField>

    <ParamField body="monthly_transaction_value" type="number">
      The total value of payments processed by the business in the past month to provide additional context for KYB review.
    </ParamField>

    <ParamField body="max_transfer_amount" type="number">
      The maximum amount the business expects to transfer in a single payment to provide additional context for KYB review.
    </ParamField>

    <ParamField body="annual_turnover" type="number">
      The annual turnover of the business to provide additional context for KYB review.
    </ParamField>

    <ParamField body="customer_types" type="string">
      The types of customers the business serves (e.g. "individuals", "other businesses", "nonprofits", etc.) to provide additional context for KYB review.
    </ParamField>

    <ParamField body="sales_channel" type="string">
      The primary sales channel for the business (e.g. "online", "in-person", "both") to provide additional context for KYB review.
    </ParamField>

    <ParamField body="funding_sources" type="string">
      The primary funding sources for the business (e.g. "bank account", "credit card", "both") to provide additional context for KYB review.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="parent_entity" type="string">
  The parent entity ID to link to for hierarchical relationship.
</ParamField>

<ParamField body="parent_relationship" type="string">
  The relationship of the business to the parent entity (e.g. "subsidiary", "affiliate", etc.).
</ParamField>

***

## Response fields

<CodeGroup>
  ```json theme={null}
  {
      "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": "01K7PMRJDFEXDH9357NAP4MMBN",
              "line_1": "Test Lane",
              "line_2": "",
              "city": "Southampton",
              "state": "England",
              "postal_code": "SO14 0AA",
              "country_code": "GB",
              "owner_id": "01K7PMRJ8M9Z0XXAZTFS7GGN8C",
              "owner_type": "business",
              "created": 1760622823855,
              "updated": 1762164348422
          },
          "entity": {
              "id": "01K7PMRJDGW97VTAMNYJ50W2E3",
              "type": "business",
              "status": "failed",
              "name": "Acme Corporation Ltd Configurable",
              "is_root": true,
              "business_id": "01K7PMRJ8M9Z0XXAZTFS7GGN8C",
              "user_id": "01K42STB6298K78CZQZ7JA1EZ9",
              "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": "01K7PMRJ8M9Z0XXAZTFS7GGN8C",
              "owner_type": "business",
              "created": 1762164348423,
              "updated": 1762164348422
          },
          "business": {
              "id": "01K7PMRJ8M9Z0XXAZTFS7GGN8C",
              "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": "01K7PMRJDF77YPGBQRAAN9W9HR",
              "business_id": "01K7PMRJ8M9Z0XXAZTFS7GGN8C",
              "meta": {
                  "tax_id": "123456789",
                  "proof_of_address": "https://res.cloudinary.com/dunf1s5lt/image/upload/v1762122872/nuvion/business/documents/tzvukdiiomb2sjf9aqxy.png",
                  "incorporation_document": "https://res.cloudinary.com/dunf1s5lt/image/upload/v1762122855/nuvion/business/incorporation/awvweye2jeehqclihpe0.png",
                  "mou_document": "https://res.cloudinary.com/dunf1s5lt/image/upload/v1762122860/nuvion/business/documents/hg07oel1t00vleuvcjqo.png",
                  "use_case": "",
                  "registration_number": "123456790"
              },
              "created": 1760622823855,
              "updated": 1762164303929
          },
          "business_officers": [
              {
                  "id": "01K7PMRJDFBY4WE1QRYN7AVC5D",
                  "person_id": "01K7PMRJB4XJAE6J23F1RD19MN",
                  "job_title": "ceo",
                  "is_control_person": true,
                  "is_beneficial_owner": true,
                  "ownership_percentage": 55,
                  "business_id": "01K7PMRJ8M9Z0XXAZTFS7GGN8C",
                  "created": 1760622823855,
                  "updated": 1760636638066
              }
          ]
      }
  }
  ```
</CodeGroup>

<ResponseField name="message" type="string">
  A human-readable message describing the result of the API call.
</ResponseField>

<ResponseField name="status" type="string">
  The status of the API call. Either `success` or `error`.
</ResponseField>

<ResponseField name="data" type="object">
  The details of the updated entity, including all related objects and the specific changes that were applied.

  <Expandable title="data">
    <ResponseField name="changes_applied" type="object">
      The list of changes applies

      <Expandable title="changes_applied">
        <ResponseField name="meta_fields" type="array">
          List of meta fields that were updated.
        </ResponseField>

        <ResponseField name="entity_fields" type="array">
          List of entity fields that were updated.
        </ResponseField>

        <ResponseField name="address_fields" type="array">
          List of address fields that were updated.
        </ResponseField>

        <ResponseField name="officers_added" type="array">
          List of officers that were added.
        </ResponseField>

        <ResponseField name="business_fields" type="array">
          List of business fields that were updated.
        </ResponseField>

        <ResponseField name="officer_removed" type="aray">
          List of officers that were removed.
        </ResponseField>

        <ResponseField name="officer_updated" type="array">
          List of officers that were updated.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="address" type="object">
      The entity's registered address object.

      <Expandable title="address">
        <ResponseField name="id" type="string">
          Unique identifier for the address.
        </ResponseField>

        <ResponseField name="line_1" type="string">
          Street address line 1.
        </ResponseField>

        <ResponseField name="line_2" type="string">
          Street address line 2.
        </ResponseField>

        <ResponseField name="city" type="string">
          City.
        </ResponseField>

        <ResponseField name="state" type="string">
          State or province.
        </ResponseField>

        <ResponseField name="postal_code" type="string">
          Postal or zip code.
        </ResponseField>

        <ResponseField name="country" type="string">
          Country.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="entity" type="object">
      The main entity object with core details and status.

      <Expandable title="entity">
        <ResponseField name="id" type="string">
          Unique identifier for the entity.
        </ResponseField>

        <ResponseField name="type" type="string">
          The entity type. Either `individual` or `business`.
        </ResponseField>

        <ResponseField name="status" type="string">
          The entity's current verification status.
        </ResponseField>

        <ResponseField name="name" type="string">
          The display name of the entity.
        </ResponseField>

        <ResponseField name="is_root" type="boolean">
          Whether this entity is a root entity or a subsidiary.
        </ResponseField>

        <ResponseField name="business_id" type="string">
          The ID of the associated business object, if applicable.
        </ResponseField>

        <ResponseField name="user_id" type="string">
          The ID of the user who created this entity, if applicable.
        </ResponseField>

        <ResponseField name="creation_context" type="string">
          How this entity was created (e.g. `user`, `api`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="operating_address" type="object">
      <Expandable title="operating_addres">
        <ResponseField name="id" type="string">
          Unique identifier for the operating address.
        </ResponseField>

        <ResponseField name="line_1" type="string">
          Street address line 1.
        </ResponseField>

        <ResponseField name="line_2" type="string">
          Street address line 2.
        </ResponseField>

        <ResponseField name="city" type="string">
          City.
        </ResponseField>

        <ResponseField name="state" type="string">
          State or province.
        </ResponseField>

        <ResponseField name="postal_code" type="string">
          Postal or zip code.
        </ResponseField>

        <ResponseField name="country" type="string">
          Country.
        </ResponseField>

        <ResponseField name="owner_id" type="string">
          The ID of the entity that owns this address.
        </ResponseField>

        <ResponseField name="owner_type" type="string">
          The type of entity that owns this address (e.g. `business`).
        </ResponseField>

        <ResponseField name="created" type="number">
          The timestamp when this address was created.
        </ResponseField>

        <ResponseField name="updated" type="number">
          The timestamp when this address was last updated.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="business" type="object">
      The business-specific details for this entity.

      <Expandable title="business">
        <ResponseField name="id" type="string">
          Unique identifier for the business details object.
        </ResponseField>

        <ResponseField name="legal_name" type="string">
          The registered legal name of the business.
        </ResponseField>

        <ResponseField name="trade_name" type="string">
          The trading name or DBA of the business.
        </ResponseField>

        <ResponseField name="email" type="string">
          The contact email for the business.
        </ResponseField>

        <ResponseField name="phonenumber" type="string">
          The contact phone number for the business.
        </ResponseField>

        <ResponseField name="registration_number" type="string">
          The government-issued registration number for the business.
        </ResponseField>

        <ResponseField name="industry" type="string">
          The industry code or description for the business.
        </ResponseField>

        <ResponseField name="website" type="string">
          The website URL for the business.
        </ResponseField>

        <ResponseField name="type" type="string">
          The legal structure of the business (e.g. `LLC`, `corporation`).
        </ResponseField>

        <ResponseField name="description" type="string">
          A description of what the business does.
        </ResponseField>

        <ResponseField name="incorporation_meta" type="object">
          Additional details about the business's incorporation.

          <Expandable title="incorporation_meta">
            <ResponseField name="year" type="number">
              The year the business was incorporated.
            </ResponseField>

            <ResponseField name="month" type="number">
              The month the business was incorporated.
            </ResponseField>

            <ResponseField name="country" type="string">
              The country where the business was incorporated.
            </ResponseField>

            <ResponseField name="state" type="string">
              The state or province where the business was incorporated.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="created" type="number">
          The timestamp when these business details were created.
        </ResponseField>

        <ResponseField name="updated" type="number">
          The timestamp when these business details were last updated.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="business_meta" type="object">
      Additional metadata related to the business entity.

      <Expandable title="business_meta">
        <ResponseField name="id" type="string">
          Unique identifier for the business meta object.
        </ResponseField>

        <ResponseField name="business_id" type="string">
          The ID of the associated business details object.
        </ResponseField>

        <ResponseField name="meta" type="object">
          A key-value store for additional metadata about the business.

          <Expandable title="meta">
            <ResponseField name="tax_id" type="string">
              The tax identification number for the business.
            </ResponseField>

            <ResponseField name="proof_of_address" type="string">
              A URL to the proof of address document for the business.
            </ResponseField>

            <ResponseField name="incorporation_document" type="string">
              A URL to the incorporation document for the business.
            </ResponseField>

            <ResponseField name="mou_document" type="string">
              A URL to the memorandum of understanding document for the business.
            </ResponseField>

            <ResponseField name="use_case" type="string">
              A description of the business's use case for Nuvion.
            </ResponseField>

            <ResponseField name="registration_number" type="string">
              The government-issued registration number for the business.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="created" type="number">
          The timestamp when this business meta was created.
        </ResponseField>

        <ResponseField name="updated" type="number">
          The timestamp when this business meta was last updated.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="business_officers" type="array">
      A list of the business officers associated with this entity.

      <Expandable title="business_officers">
        <ResponseField name="id" type="string">
          Unique identifier for the business officer record.
        </ResponseField>

        <ResponseField name="person_id" type="string">
          The ID of the person associated with this officer.
        </ResponseField>

        <ResponseField name="job_title" type="string">
          The job title of the officer within the business.
        </ResponseField>

        <ResponseField name="is_control_person" type="boolean">
          Whether this officer has significant control over the business.
        </ResponseField>

        <ResponseField name="is_beneficial_owner" type="boolean">
          Whether this officer is a beneficial owner of the business.
        </ResponseField>

        <ResponseField name="ownership_percentage" type="number">
          The percentage of ownership this officer has in the business.
        </ResponseField>

        <ResponseField name="business_id" type="string">
          The ID of the associated business details object.
        </ResponseField>

        <ResponseField name="created" type="number">
          The timestamp when this business officer record was created.
        </ResponseField>

        <ResponseField name="updated" type="number">
          The timestamp when this business officer record was last updated.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Get an entity

Retrieves an existing entity by ID.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.nuvion.dev/entities/01HXYZ1234ABCD \
    -H "Authorization: Bearer $NUVION_API_KEY"
  ```
</CodeGroup>

### Request parameters

<ParamField path="entity_id" type="string" required>
  The ID of the entity to retrieve.
</ParamField>

### Response

Returns the entity object.

```json Response theme={null}
{
  "id": "01HXYZ1234ABCD",
  "type": "individual",
  "status": "approved",
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "date_of_birth": "1990-06-15",
    "country_of_residence": "US"
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725900000
}
```

***

## Entity statuses

| Status      | Description                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `pending`   | Entity created or 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. |
| `suspended` | Account access temporarily restricted. Contact support to resolve.                             |