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, it 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
`failed`	Verification failed
`suspended`	Entity has been suspended. Contact Nuvion support

incomplete → pending → approved
                ├→ rejected → (resubmit) → pending
                └→ failed

The Entity object

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

See The Entity object for the full field-by-field schema. Nuvion doesn’t nest identity details, business details, or metadata inside the entity object. It returns them as sibling objects (person or business, and person_meta or business_meta) alongside entity in create and retrieve responses.

Creating a business entity

Onboard a business entity in three steps: 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": "App Business Ltd",
    "business": {
      "legal_name": "App Technologies Limited",
      "trade_name": "App Tech",
      "industry": "Technology",
      "email": "finance@acmetech.com",
      "website": "https://acmetech.com",
      "type": "llc",
      "description": "A B2B SaaS platform for logistics management.",
      "registration_number": "47-7654334",
      "phonenumber": "+12125550199",
      "incorporation_meta": {
        "year": 2019,
        "month": 4,
        "country": "US",
        "state": "Delaware"
      }
    },
    "address": {
      "line_1": "350 Fifth Avenue",
      "city": "New York",
      "state": "New York",
      "postal_code": "10118",
      "country_code": "US"
    },
    "operating_address": {
      "line_1": "350 Fifth Avenue",
      "city": "New York",
      "state": "New York",
      "postal_code": "10118",
      "country_code": "US"
    },
    "business_officers": [
      {
        "job_title": "Chief Executive Officer",
        "is_control_person": true,
        "is_beneficial_owner": true,
        "ownership_percentage": 60,
        "person": {
          "first_name": "Alex",
          "last_name": "Johnson",
          "date_of_birth": "1985-06-15",
          "email": "alex.johnson@acmetech.com",
          "nationality": "US",
          "gender": "m",
          "phonenumber": "+12125550198",
          "bvn": "23487892834",
          "nin": "25856743645",
          "ssn": "123-45-6789",
          "identification": {
            "document": {
              "type": "international_passport",
              "number": "P123456789",
              "issue_date": "2020-01-10",
              "expiry_date": "2030-01-09",
              "issuing_country": "US"
            },
            "proof_of_address": {
              "type": "utility_bill"
            }
          },
          "address": {
            "line_1": "210 West 77th Street",
            "city": "New York",
            "state": "New York",
            "postal_code": "10024",
            "country_code": "US"
          }
        }
      }
    ],
    "meta": {
      "registration_number": "47-7654334",
      "tax_id": "47-1234589",
      "annual_turnover": "5M",
      "monthly_transaction_value": "500K",
      "monthly_payments_count": "200",
      "max_transfer_amount": "100K",
      "customer_types": "Individual",
      "sales_channels": "My own website",
      "funding_source": "Revenue from software subscriptions",
      "liveness_check_id": "liv_01HXYZ1234ABCD"
    }
  }'

Request fields

string

required

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

object

required

Core business information.

Show business fields

string

required

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

string

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

string

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

string

required

Business contact email address.

string

required

Business website URL.

string

required

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

string

required

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

string

required

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

string

required

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

object

required

Details of when and where the business was incorporated.

Show incorporation_meta fields

number

required

Year of incorporation.

number

Month of incorporation. 1–12.

string

required

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

string

State or province of incorporation. 1–100 characters.

object

Registered address of the business.

Show address fields

string

required

Street address line 1. 1–255 characters.

string

Street address line 2. Max 255 characters.

string

Street address line 3. Max 255 characters.

string

required

City. 1–100 characters.

string

required

State or province. 1–100 characters.

string

required

Postal or ZIP code. 1–20 characters.

string

required

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

object

Additional address metadata.

object

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

array

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

Show business_officers fields

string

required

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

boolean

required

Whether this person has significant management control over the business.

boolean

required

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

number

required

The officer’s ownership stake. 0–100.

object

Personal details for the officer. See Person object below.

object

Additional compliance and business metadata.

Show meta fields

string

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

string

Tax identification number.

string

required

Estimated annual revenue.

string

required

Expected monthly transaction volume.

string

required

Expected number of monthly payments.

string

required

Maximum single transfer amount.

string

required

Description of the business’s customer base.

string

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

string

required

Primary source of funds for the business.

string

Reference ID from a liveness or biometric check.

string

Description of this entity’s relationship to its parent, if it’s a subsidiary or related entity. You can’t set the parent via a request field: it’s always the authenticating entity. See Managing child entities.

Person object

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

string

required

1–100 characters.

string

required

1–100 characters.

string

Max 100 characters.

string

required

Format: YYYY-MM-DD.

string

required

Valid email address.

string

required

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

string

required

m for male, f for female.

string

Phone number including country code. 10–14 characters.

string

Bank Verification Number (BVN) required for Nigerian nationals.

string

National Identity Number (NIN) required for Nigerian nationals.

string

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

object

Identity verification documents for this person.

Show identification fields

object

required

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

Show document fields

string

required

Document type. One of international_passport, drivers_license, national_id.

string

required

Document number.

string

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

string

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

string

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

string

Name of the authority that issued the document.

object

Additional fields for country-specific document types.

Show type_specific fields

string

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

object

Address verification document.

Show proof_of_address fields

string

required

One of utility_bill, bank_statement.

object

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

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

Optional business documents

Document	`key`	Accepted formats
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": "01HXYZ0016ABCDEFGHJKMNPQRS",
    "key": "certificate_of_incorporation",
    "description": "Certificate of Incorporation for App 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": "01HXYZ0016ABCDEFGHJKMNPQRS",
    "key": "identity",
    "description": "International passport for Alex Johnson",
    "file": "base64_encoded_front_here",
    "file_back": "base64_encoded_back_here",
    "meta": {
      "file_type": "application/pdf"
    },
    "link_to_identity": {
      "person_id": "01HXYZ0005ABCDEFGHJKMNPQRS"
    }
  }'

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": "01HXYZ0016ABCDEFGHJKMNPQRS"
  }'

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.

Creating an individual entity

Individual entities represent natural persons on your platform. Onboard one in the same three steps as a business entity: 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",
      "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",
        "type_specific": {
          "id_subtype": "SSN"
        }
      },
      "proof_of_address": {
        "type": "utility_bill"
      }
    },
    "meta": {
      "funding_source": "salary",
      "monthly_transaction_value": "5000",
      "tax_id": "TAX-1234567890",
      "annual_turnover": "60000",
      "customer_types": "individual",
      "monthly_payments_count": "10",
      "max_transfer_amount": "10000",
      "sales_channels": "My own website"
    }
  }'

The response includes an entity_id and a person_id. You 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

Phone number including country code. 10–14 characters.

string

Bank Verification Number (BVN) required for Nigerian nationals.

string

National Identity Number (NIN) required for Nigerian nationals.

string

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

object

Residential address of the individual.

Show address fields

string

required

Street address line 1. 1–255 characters.

string

Street address line 2. Max 255 characters.

string

Street address line 3. Max 255 characters.

string

required

City. 1–100 characters.

string

required

State or province. 1–100 characters.

string

required

Postal or ZIP code. 1–20 characters.

string

required

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

object

Additional address metadata.

object

Identity and address verification documents.

Show identification fields

object

Government-issued identity document.

Show document fields

string

required

Document type. One of international_passport, drivers_license, national_id.

string

required

Document number.

string

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

string

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

string

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

string

Name of the authority that issued the document.

object

Additional fields for country-specific document types.

Show type_specific fields

string

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

object

Address verification document.

Show proof_of_address fields

string

required

One of utility_bill, bank_statement.

object

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

Show business fields

string

required

Trading name. 1–100 characters.

string

required

Description of the business activity. 1–200 characters.

string

required

Business category code. 1–100 characters.

string

Business sub-category code. 1–100 characters.

string

Business website URL.

string

URL of a liveness or biometric report for this individual.

object

Additional compliance and risk metadata.

Show meta fields

string

Tax identification number.

string

Expected number of monthly payments.

string

Expected monthly transaction volume.

string

Maximum single transfer amount.

string

Estimated annual income or revenue.

string

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

string

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

string

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

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	`proof_of_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": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "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": "01HXYZ5678ABCDEFGHJKMNPQRS"
    }
  }'

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

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": "01HXYZ1234ABCDEFGHJKMNPQRS"
  }'

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

Webhooks

Nuvion fires entities.created when a new entity is created, and entities.updated whenever its state changes afterward, for example when status moves from pending to approved. Subscribe to these to keep your platform in sync without polling. See Event types for full payload schemas.

{
  "event": "entities.created",
  "data": {
    "id": "01HXYZ0016ABCDEFGHJKMNPQRS",
    "type": "business",
    "status": "incomplete",
    "name": "App Business Ltd",
    "is_root": false,
    "parent_entity": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "business_id": "01HXYZ0015ABCDEFGHJKMNPQRS",
    "user_id": "01HXYZ0003ABCDEFGHJKMNPQRS",
    "creation_context": "api",
    "risk_level": "medium",
    "created": 1787487225040,
    "updated": 1787487225040
  }
}

{
  "event": "entities.updated",
  "data": {
    "id": "01HXYZ0016ABCDEFGHJKMNPQRS",
    "type": "business",
    "status": "approved",
    "name": "App Business Ltd",
    "is_root": false,
    "parent_entity": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "business_id": "01HXYZ0015ABCDEFGHJKMNPQRS",
    "user_id": "01HXYZ0003ABCDEFGHJKMNPQRS",
    "creation_context": "api",
    "risk_level": "medium",
    "created": 1787487225040,
    "updated": 1787487593518
  }
}

Managing child entities

Creating an entity via the API with another entity’s API keys establishes a parent-child relationship: the authenticating entity becomes the parent, and the new entity becomes the child. To act on behalf of a child entity using the parent’s API keys, pass the child’s entity_id on every request:

POST, PUT, PATCH: include entity_id in the request body.
GET: append entity_id as a query parameter.

Omitting entity_id evaluates the request against the authenticating (parent) entity, not the child. Referencing a child’s resource IDs (account_id, counterparty_id, payment_detail_id) without the child’s entity_id fails, because Nuvion validates those resources against the parent entity, where they don’t exist. This is a common cause of unexpected 404 errors.

Example

Say a parent entity has already onboarded a child entity, 01HP3MMTGM973EHJMA9K4F4CJK. Using the parent’s API key, create an account for that child by passing its entity_id:

curl -X POST https://api.nuvion.dev/accounts \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HP3MMTGM973EHJMA9K4F4CJK",
    "type": "checking",
    "currency": "USD",
    "display_name": "Child Operating USD"
  }'

{
  "status": "success",
  "message": "Account created successfully",
  "data": {
    "account": {
      "id": "01HP4NHTE7HHYDD4MHVT0ZZ3CH",
      "entity_id": "01HP3MMTGM973EHJMA9K4F4CJK",
      "type": "checking",
      "currency": "USD",
      "display_name": "Child Operating USD",
      "config": {
        "overdraft_limit": 0,
        "balance_next_refresh": 0,
        "is_overdraftable": false,
        "balance_refresh_interval": 15
      },
      "balance": {
        "available": 0,
        "current": 0,
        "overdraft_used": 0
      },
      "stablecoin_assets": {},
      "maintenance_fee_opted_out": false,
      "system_meta": {},
      "created": 1788800000000,
      "updated": 1788800000000,
      "deleted": 0,
      "meta": {},
      "nuvion_ban": "0010759003"
    },
    "entity_impact": {
      "entity_id": "01HP3MMTGM973EHJMA9K4F4CJK",
      "total_accounts": 1,
      "account_type": [
        "checking"
      ],
      "default_account_set": true
    }
  }
}

The account (01HP4NHTE7HHYDD4MHVT0ZZ3CH) now belongs to the child entity, not the parent. Fetching it with the parent’s API key but no entity_id fails, because Nuvion looks for the account under the parent (the authenticating entity), where it doesn’t exist:

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

Returns 404 Not Found:

{
  "status": "error",
  "message": "We couldn't find that account. It may have been deleted or the ID might be incorrect.",
  "type": "error_resource_not_found"
}

Passing the child’s entity_id resolves it:

curl "https://api.nuvion.dev/accounts/01HP4NHTE7HHYDD4MHVT0ZZ3CH?entity_id=01HP3MMTGM973EHJMA9K4F4CJK" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Pass entity_id consistently across every request in a workflow, and make sure every resource ID belongs to that same entity.

Webhooks follow the same hierarchy: a child entity without its own webhook has its events delivered to its parent’s webhook instead. See Child entities for details.

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

Creating an individual entity

Step 1: Create the entity

Request fields

Step 2: Upload documents

Step 3: Submit for verification

Webhooks

Managing child entities

Example

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

​Creating an individual entity

​Step 1: Create the entity

​Request fields

​Step 2: Upload documents

​Step 3: Submit for verification

​Webhooks

​Managing child entities

​Example

​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

Creating an individual entity

Step 1: Create the entity

Request fields

Step 2: Upload documents

Step 3: Submit for verification

Webhooks

Managing child entities

Example

What’s next