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

> An entity represents a person or business on your platform. Entities own accounts, initiate transactions, and must be verified before they can transact.

An entity is the foundational object in Nuvion. Everything — accounts, transactions, payouts — belongs to an entity. Before an entity can hold funds or move money, they must complete verification through Nuvion's onboarding flow.

## Entity types

| Type         | Description                           |
| ------------ | ------------------------------------- |
| `individual` | A natural person on your platform     |
| `business`   | A registered business or legal entity |

***

## Entity statuses

Entities move through a defined lifecycle from creation to activation.

| Status       | Description                                                                      |
| ------------ | -------------------------------------------------------------------------------- |
| `incomplete` | Entity has been created but is missing required information or documents         |
| `pending`    | Entity has been submitted for review and verification is underway                |
| `approved`   | Verification is complete — the entity can create accounts and transact           |
| `rejected`   | Verification failed — rejection reasons are provided and the entity may resubmit |
| `suspended`  | Entity has been suspended — contact Nuvion support                               |

```
incomplete → pending → approved
                ↓
             rejected → (resubmit) → pending
```

<Note>
  An entity must be approved before it or its associated API can be used
</Note>

***

## The entity object

<Info>
  The full response schema is pending confirmation. The fields below reflect what is currently known. This section will be updated.
</Info>

```json theme={null}
{
  "id": "ent_01HXYZ1234ABCD",
  "object": "entity",
  "type": "business",
  "status": "approved",
  "pending_verification_requirements": [],
  "created_at": "2026-01-01T10:00:00Z",
  "updated_at": "2026-01-01T10:30:00Z"
}
```

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

<ResponseField name="object" type="string">
  Always `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. One of `incomplete`, `pending`, `approved`, `rejected`, `suspended`.
</ResponseField>

<ResponseField name="pending_verification_requirements" type="array">
  A list of items still required before the entity can be submitted for verification. Empty when the entity is ready to submit.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the entity was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the last update to the entity.
</ResponseField>

***

## Creating a business entity

Business entity creation is a three-step process: create the entity, upload documents, then submit for verification.

### Step 1: Create the entity

<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>

***

### Step 2: Upload documents

Upload the required documents for the business and each officer. Documents must be base64-encoded.

**Required business documents**

| Document                     | `key`                          | Accepted formats    |
| ---------------------------- | ------------------------------ | ------------------- |
| Certificate of Incorporation | `certificate_of_incorporation` | PDF                 |
| Memorandum of Association    | `memorandum_of_association`    | PDF, DOCX           |
| Proof of Address             | `proof_of_address`             | PDF, JPG, JPEG, PNG |
| Tax Verification Document    | `tax_verification`             | PDF                 |

**Required per officer**

| Document             | `key`              |
| -------------------- | ------------------ |
| Government-issued ID | `identity`         |
| Proof of address     | `proof_of_address` |

<Note>
  `BVN` and `NIN` are required for Nigerian nationals. `SSN` is required for U.S. nationals.
</Note>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/documents \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entity_id": "ent_01HXYZ1234ABCD",
      "key": "certificate_of_incorporation",
      "description": "Certificate of Incorporation for Acme Technologies Limited",
      "file": "base64_encoded_content_here",
      "meta": {
        "file_type": "application/pdf"
      }
    }'
  ```
</CodeGroup>

To link a document to a specific officer, include `link_to_identity` with the officer's `person_id`:

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

#### Request fields

<ParamField body="entity_id" type="string">
  ULID of the entity to attach the document to. Required when uploading via the API.
</ParamField>

<ParamField body="file" type="string" required>
  Base64-encoded file content. Accepted formats: PDF, JPG, JPEG, PNG, DOC, DOCX.
</ParamField>

<ParamField body="file_back" type="string">
  Base64-encoded back side of the document. Use for identity documents that have information on both sides.
</ParamField>

<ParamField body="description" type="string" required>
  A human-readable description of the document. 1–500 characters.
</ParamField>

<ParamField body="key" type="string">
  The document type. One of `identity`, `proof_of_address`, `tax_verification`, `certificate_of_incorporation`, `memorandum_of_association`.
</ParamField>

<ParamField body="meta" type="object">
  Additional document metadata.

  <Expandable title="meta fields">
    <ParamField body="file_type" type="string">
      MIME type of the document. e.g. `application/pdf`, `image/jpeg`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="link_to_identity" type="object">
  Links this document to a specific business officer. Required when uploading identity or address documents for an officer.

  <Expandable title="link_to_identity fields">
    <ParamField body="person_id" type="string" required>
      ULID of the person to link this document to.
    </ParamField>
  </Expandable>
</ParamField>

***

### Step 3: Submit for verification

Once all required documents are uploaded, submit the entity for review.

<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": "ent_01HXYZ1234ABCD"
    }'
  ```
</CodeGroup>

The entity status moves to `pending`. Nuvion's compliance team reviews the submission and updates the status to `approved` or `rejected`.

<Tip>
  Don't poll `GET /entities/:id` to check status. Listen for the `entities.updated` webhook event instead.
</Tip>

***

### Resubmitting after rejection

If an entity is `rejected`, the rejection response includes the reasons. Correct the relevant information or documents and call `POST /onboarding-submissions` again.

<Info>
  The full resubmission flow is pending confirmation with engineering. This section will be updated.
</Info>

***

## Creating an individual entity

Individual entities represent natural persons on your platform. Onboarding follows the same three-step flow as business entities: create the entity, upload identity documents, then submit for verification.

### Step 1: Create the entity

<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": "doc_01HXYZ1234ABCD",
          "type_specific": {
            "id_subtype": "SSN"
          }
        },
        "proof_of_address": {
          "type": "utility_bill",
          "document_id": "doc_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>

The response includes an `entity_id` and a `person_id`. You will need the `person_id` to link identity documents to this individual in Step 2.

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

***

### Step 2: Upload documents

Upload two required documents for the individual via `POST /documents`. Documents must be base64-encoded.

| Document             | `key`      | Accepted types                                                                             |
| -------------------- | ---------- | ------------------------------------------------------------------------------------------ |
| Government-issued ID | `identity` | Passport, driver's license, national ID                                                    |
| Proof of address     | `address`  | Utility bill, bank statement, or government correspondence — must be dated within 3 months |

<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": "ent_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": "ent_01HXYZ1234ABCD",
      "key": "address",
      "description": "Utility bill for Alex Johnson",
      "file": "base64_encoded_content_here",
      "meta": {
        "file_type": "application/pdf"
      },
      "link_to_identity": {
        "person_id": "per_01HXYZ1234ABCD"
      }
    }'
  ```
</CodeGroup>

***

### Step 3: Submit for verification

Once both documents are uploaded, submit the entity for review.

<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": "ent_01HXYZ1234ABCD"
    }'
  ```
</CodeGroup>

The entity status moves to `pending`. Listen for the `entities.updated` webhook to be notified when verification completes.

***

## Webhooks

Nuvion emits events when entity state changes. Subscribe to these to keep your platform in sync without polling.

| Event              | When it fires                                       |
| ------------------ | --------------------------------------------------- |
| `entities.updated` | Entity status changes (e.g. `pending` → `approved`) |

<Info>
  Full event payload schemas are pending confirmation with engineering. This section will be updated.
</Info>

***

## What's next

<CardGroup cols={3}>
  <Card title="Create an account" icon="building-columns" href="/core-concepts/accounts">
    Issue a multi-currency account for an approved entity.
  </Card>

  <Card title="Entities API reference" icon="code" href="/api-reference/entities">
    Full endpoint documentation for creating and managing entities.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/overview">
    Set up webhook listeners for entity and document events.
  </Card>
</CardGroup>