Entities

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

An entity must be approved before it or its associated API can be used

The entity object

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

{
  "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"
}

string

Unique identifier for the entity. ULID format.

string

Always entity.

string

The entity type. Either individual or business.

string

The entity’s current verification status. One of incomplete, pending, approved, rejected, suspended.

array

A list of items still required before the entity can be submitted for verification. Empty when the entity is ready to submit.

string

ISO 8601 timestamp of when the entity was created.

string

ISO 8601 timestamp of the last update to the entity.

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

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"
    }
  }'

Request fields

string

required

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

object

required

Core business information.

Show business fields

string

required

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

string

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

string

required

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

string

required

Business contact email address.

string

Business website URL.

string

required

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

string

required

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

string

required

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

string

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

object

required

Details of when and where the business was incorporated.

Show incorporation_meta fields

number

required

Year of incorporation.

number

required

Month of incorporation. 1–12.

string

required

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

string

required

State or province of incorporation. 1–100 characters.

object

Registered address of the business.

Show address fields

string

required

Street address line 1. 1–255 characters.

string

Street address line 2. Max 255 characters.

string

Street address line 3. Max 255 characters.

string

required

City. 1–100 characters.

string

required

State or province. 1–100 characters.

string

required

Postal or ZIP code. 1–20 characters.

string

required

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

object

Additional address metadata.

object

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

array

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

Show business_officers fields

string

required

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

boolean

required

Whether this person has significant management control over the business.

boolean

required

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

number

required

The officer’s ownership stake. 0–100.

object

Personal details for the officer. See Person object below.

object

Additional compliance and business metadata.

Show meta fields

string

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

string

Tax identification number.

string

Estimated annual revenue.

string

Expected monthly transaction volume.

string

Expected number of monthly payments.

string

Maximum single transfer amount.

string

Description of the business’s customer base.

string

Channels through which the business sells (e.g. online, in-person).

string

Primary source of funds for the business.

string

Reference ID from a liveness or biometric check.

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.

Person object

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

string

required

1–100 characters.

string

required

1–100 characters.

string

Max 100 characters.

string

required

Format: YYYY-MM-DD.

string

required

Valid email address.

string

required

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

string

required

m for male, f for female.

string

required

Phone number including country code. 10–14 characters.

string

Bank Verification Number (BVN) required for Nigerian nationals.

string

National Identity Number (NIN) required for Nigerian nationals.

string

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

object

Identity verification documents for this person.

Show identification fields

object

required

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

Show document fields

string

required

Document type. One of international_passport, drivers_license, national_id.

string

required

Document number.

string

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

string

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

string

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

string

Name of the authority that issued the document.

object

Additional fields for country-specific document types.

Show type_specific fields

string

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

object

Address verification document.

Show proof_of_address fields

string

required

One of utility_bill, bank_statement.

object

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

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`

BVN and NIN are required for Nigerian nationals. SSN is required for U.S. nationals.

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"
    }
  }'

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

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"
    }
  }'

Request fields

string

ULID of the entity to attach the document to. Required when uploading via the API.

string

required

Base64-encoded file content. Accepted formats: PDF, JPG, JPEG, PNG, DOC, DOCX.

string

Base64-encoded back side of the document. Use for identity documents that have information on both sides.

string

required

A human-readable description of the document. 1–500 characters.

string

The document type. One of identity, proof_of_address, tax_verification, certificate_of_incorporation, memorandum_of_association.

object

Additional document metadata.

Show meta fields

string

MIME type of the document. e.g. application/pdf, image/jpeg.

object

Links this document to a specific business officer. Required when uploading identity or address documents for an officer.

Show link_to_identity fields

string

required

ULID of the person to link this document to.

Step 3: Submit for verification

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

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"
  }'

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

Don’t poll GET /entities/:id to check status. Listen for the entities.updated webhook event instead.

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.

The full resubmission flow is pending confirmation with engineering. This section will be updated.

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

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",
    }
  }'

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

string

required

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

object

required

Personal details for the individual.

Show person fields

string

required

1–100 characters.

string

required

1–100 characters.

string

Max 100 characters.

string

required

Format: YYYY-MM-DD.

string

required

Valid email address.

string

required

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

string

required

m for male, f for female.

string

required

Phone number including country code. 10–14 characters.

string

Bank Verification Number (BVN) required for Nigerian nationals.

string

National Identity Number (NIN) required for Nigerian nationals.

string

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

object

Residential address of the individual.

Show address fields

string

required

Street address line 1. 1–255 characters.

string

Street address line 2. Max 255 characters.

string

Street address line 3. Max 255 characters.

string

required

City. 1–100 characters.

string

required

State or province. 1–100 characters.

string

required

Postal or ZIP code. 1–20 characters.

string

required

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

object

Additional address metadata.

object

Identity and address verification documents.

Show identification fields

object

Government-issued identity document.

Show document fields

string

required

Document type. One of international_passport, drivers_license, national_id.

string

required

Document number.

string

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

string

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

string

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

string

Name of the authority that issued the document.

object

Additional fields for country-specific document types.

Show type_specific fields

string

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

object

Address verification document.

Show proof_of_address fields

string

required

One of utility_bill, bank_statement.

object

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

Show business fields

string

required

Trading name. 1–100 characters.

string

required

Description of the business activity. 1–200 characters.

string

required

Business category code. 1–100 characters.

string

Business sub-category code. 1–100 characters.

string

Business website URL.

string

URL of a liveness or biometric report for this individual.

object

Additional compliance and risk metadata.

Show meta fields

string

Tax identification number.

string

Expected number of monthly payments.

string

Expected monthly transaction volume.

string

Maximum single transfer amount.

string

Estimated annual income or revenue.

string

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

string

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

string

The ID of a parent entity, if this individual is associated with a business entity. 26-character ULID.

string

Description of the relationship to the parent entity. 1–100 characters.

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

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"
    }
  }'

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"
    }
  }'

Step 3: Submit for verification

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

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"
  }'

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

Full event payload schemas are pending confirmation with engineering. This section will be updated.

What’s next

Create an account

Issue a multi-currency account for an approved entity.

Entities API reference

Full endpoint documentation for creating and managing entities.

Webhooks

Set up webhook listeners for entity and document events.

Get Started

Core Concepts

Webhooks

Guides

Entity types

Entity statuses

The entity object

Creating a business entity

Step 1: Create the entity

Request fields

Person object

Step 2: Upload documents

Request fields

Step 3: Submit for verification

Resubmitting after rejection

Creating an individual entity

Step 1: Create the entity

Request fields

Step 2: Upload documents

Step 3: Submit for verification

Webhooks

What’s next

Create an account

Entities API reference

Webhooks

​Entity types

​Entity statuses

​The entity object

​Creating a business entity

​Step 1: Create the entity

​Request fields

​Person object

​Step 2: Upload documents

​Request fields

​Step 3: Submit for verification

​Resubmitting after rejection

​Creating an individual entity

​Step 1: Create the entity

​Request fields

​Step 2: Upload documents

​Step 3: Submit for verification

​Webhooks

​What’s next

Create an account

Entities API reference

Webhooks

Entity types

Entity statuses

The entity object

Creating a business entity

Step 1: Create the entity

Request fields

Person object

Step 2: Upload documents

Request fields

Step 3: Submit for verification

Resubmitting after rejection

Creating an individual entity

Step 1: Create the entity

Request fields

Step 2: Upload documents

Step 3: Submit for verification

Webhooks

What’s next