Entities - Nuvion

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

The Entity object

string

Unique entity identifier. Prefix: ent_.

type

string

individual or business.

status

string

Review state. One of pending, approved, rejected, or suspended. See Entity statuses below.

profile

object

Identity details. Shape depends on type.

Show Individual profile fields

first_name

string

Legal first name.

last_name

string

Legal last name.

string

Contact email address.

date_of_birth

string

Date of birth in YYYY-MM-DD format.

country_of_residence

string

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

Show Business profile fields

legal_name

string

Full registered legal name of the business.

string

Business contact email address.

business_type

string

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

country_of_incorporation

string

ISO 3166-1 alpha-2 country code where the business is incorporated.

meta

object

Set of key-value pairs for storing additional platform-defined data.

created

number

Unix timestamp in milliseconds when the entity was created.

updated

number

Unix timestamp in milliseconds when the entity was last updated.

Example

{
  "id": "ent_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.

curl -X POST https://api.nuvion.dev/individual-entities \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "date_of_birth": "1990-06-15",
    "country_of_residence": "US"
  }'

Request parameters

first_name

string

required

Legal first name of the individual.

last_name

string

required

Legal last name of the individual.

string

required

Contact email address. Must be a valid email format.

date_of_birth

string

required

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

country_of_residence

string

required

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

meta

object

Key-value metadata to attach to the entity. Values must be strings.

Response

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

Response

{
  "id": "ent_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
}

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

Update an individual entity

Updates the profile of an existing individual entity.

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

Request parameters

name

string

The name of the individual entity.

person

object

The profile details of the individual entity.

Show person fields

first_name

string

Legal first name of the individual.

last_name

string

Legal last name of the individual.

string

Contact email address. Must be a valid email format.

date_of_birth

string

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

nationality

string

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

gender

string

The individual’s gender. One of M, F, or Other.

phonenumber

string

The individual’s phone number.

address

object

The address of the individual entity.

Show address fields

line_1

string

Street address line 1.

line_2

string

Street address line 2.

line_3

string

Street address line 3.

metal_line

string

Additional address metadata.

city

string

City.

state

string

State/province/region.

postal_code

string

Postal or ZIP code.

country_code

string

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

business

object

Show business fields

website

string

Full registered legal name of the business.

name

string

Business contact name

liveness_report_url

string

Business liveness report url.

description

string

Business description.

category_code

string

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

sub_category_code

string

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

identification

object

The identification details of the individual entity.

Show identification fields

document

object

The identification document details.

Show document fields

type

string

The type of identification document. One of passport, driver_license, or national_id.

number

string

The identification document number.

issue_date

string

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

expiry_date

string

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

issuing_country

string

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

issuing_authority

string

The authority that issued the identification document.

document_id

string

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

type_specific

object

Additional fields specific to the type of identification document.

Show type_specific fields

proof_of_address

object

The proof of address document details.

Show proof_of_address fields

type

string

The utility bill document type (utility|Bank statement).

document_id

string

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

parent_entity

string

The parent entity. This links the individual to the to the parent entity for hierarchical relationship.

parent_relationship

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

Sample Response

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

Response fields

message

string

A message describing the result of the update operation.

status

string

The status of the update operation.

data

object

The updated entity data.

Show data

changes_applied

object

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

address

array

The updated address object for the individual entity.

entity

array

The updated entity object for the individual entity.

person

array

The updated person object for the individual entity.

identification

array

The updated identification object for the individual entity.

address

object

The updated address details of the individual entity.

Show address fields

line_1

string

Street address line 1.

line_2

string

Street address line 2.

line_3

string

Street address line 3.

meta

string

Additional address metadata.

city

string

City.

state

string

State/province/region.

postal_code

string

Postal or ZIP code.

country_code

string

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

owner_id

string

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

owner_type

string

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

created

number

Unix timestamp in milliseconds when the address was created.

updated

number

Unix timestamp in milliseconds when the address was last updated.

entity

object

The updated entity details of the individual entity.

Show entity fields

string

Unique entity identifier. Prefix: ent_.

type

string

individual or business.

status

string

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

name

string

The name of the individual entity.

is_root

boolean

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

user_id

string

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

creation_context

string

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

created

number

Unix timestamp in milliseconds when the entity was created.

updated

number

Unix timestamp in milliseconds when the entity was last updated.

person

object

The updated person details of the individual entity.

Show person fields

first_name

string

Legal first name of the individual.

last_name

string

Legal last name of the individual.

middle_name

string

Middle name of the individual.

date_of_birth

string

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

string

Contact email address. Must be a valid email format.

nationality

string

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

gender

string

The individual’s gender. One of M, F, or Other.

is_pep

boolean

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

status

string

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

phonenumber

string

The individual’s phone number.

created

number

Unix timestamp in milliseconds when the person profile was created.

updated

number

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

identification

object

The updated identification details of the individual entity.

Show identification fields

verification_status

string

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

created

number

Unix timestamp in milliseconds when the identification details were created.

updated

number

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

proof_of_address

object

The updated proof of address document details.

Show proof_of_address fields

type

string

The utility bill document type (utility|Bank statement).

document_id

string

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

verification_status

string

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

Create a business entity

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

curl -X POST https://api.nuvion.dev/business-entities \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Acme Corp Ltd",
    "email": "accounts@acmecorp.com",
    "business_type": "llc",
    "country_of_incorporation": "US",
    "registered_address": {
      "line_1": "456 Business Ave",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country_code": "US"
    }
  }'

Request parameters

legal_name

string

required

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

string

required

Business contact email address.

business_type

string

required

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

country_of_incorporation

string

required

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

registered_address

object

required

The official registered address of the business.

Show registered_address fields

line_1

string

required

Street address line 1.

city

string

required

City.

state

string

State or province. Recommended for US addresses.

postal_code

string

required

Postal or ZIP code.

country_code

string

required

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

trading_name

string

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

meta

object

Key-value metadata to attach to the entity. Values must be strings.

Response

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

Response

{
  "id": "ent_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 proof of identity and one proof of address.

curl -X POST https://api.nuvion.dev/documents/upload \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -F "key=identity" \
  -F "link_to_identity[person_id]=pid_01HXYZ5678ABCD" \
  -F "file=@/path/to/passport.pdf"

Request parameters

This endpoint uses multipart/form-data. Do not set Content-Type: application/json.

key

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

link_to_identity[person_id]

string

required

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

file

required

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

Response

{
  "id": "doc_01HXYZ3456MNOP",
  "key": "identity",
  "status": "uploaded",
  "created": 1735725600000
}

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

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.

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

Request parameters

entity_id

string

required

The ID of the entity to submit for review.

Response

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

Response

{
  "id": "ent_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.

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

Request Parameters

name

string

The name of the business entity.

business

object

The profile details of the business entity.

Show business fields

legal_name

string

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

trade_name

string

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

website

string

The business’s website URL.

description

string

A description of the business.

type

string

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

phonenumber

string

The business’s phone number.

string

The business’s contact email address.

registration_number

string

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

incorporation_meta

object

Additional details about the business’s incorporation.

Show incorporation_meta fields

year

string

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

month

string

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

country

string

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

state

string

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

address

object

The registered address of the business.

Show address fields

line_1

string

Street address line 1.

line_2

string

Street address line 2.

line_3

string

Street address line 3.

meta

string

Additional address metadata.

city

string

City.

state

string

State or province.

postal_code

string

Postal or ZIP code.

country_code

string

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

operating_address

object

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

Show operating_address fields

line_1

string

Street address line 1.

line_2

string

Street address line 2.

line_3

string

Street address line 3.

meta

string

Additional address metadata.

city

string

City.

state

string

State or province.

postal_code

string

Postal or ZIP code.

country_code

string

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

business_officers

array

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

Show business_officers fields

string

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

person_id

string

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

job_title

string

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

is_control_person

boolean

Whether the officer is a control person for the business.

is_beneficial_owner

boolean

Whether the officer is a beneficial owner of the business.

ownership_percentage

number

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

action

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.

meta

object

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

Show meta fields

registration_number

string

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

tax_id

string

The business’s tax identification number.

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 (e.g. “subsidiary”, “affiliate”, etc.).

Response fields

{
    "message": "Business entity updated successfully",
    "status": "success",
    "data": {
        "changes_applied": {
            "meta_fields": [],
            "entity_fields": [],
            "address_fields": [],
            "officers_added": [],
            "business_fields": [],
            "officers_removed": [],
            "officers_updated": []
        },
        "address": {
            "id": "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
            }
        ]
    }
}

message

string

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

status

string

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

data

object

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

Show data

changes_applied

object

The list of changes applies

Show changes_applied

meta_fields

array

List of meta fields that were updated.

entity_fields

array

List of entity fields that were updated.

address_fields

array

List of address fields that were updated.

officers_added

array

List of officers that were added.

business_fields

array

List of business fields that were updated.

officer_removed

aray

List of officers that were removed.

officer_updated

array

List of officers that were updated.

address

object

The entity’s registered address object.

Show address

string

Unique identifier for the address.

line_1

string

Street address line 1.

line_2

string

Street address line 2.

city

string

City.

state

string

State or province.

postal_code

string

Postal or zip code.

country

string

Country.

entity

object

The main entity object with core details and status.

Show entity

string

Unique identifier for the entity.

type

string

The entity type. Either individual or business.

status

string

The entity’s current verification status.

name

string

The display name of the entity.

is_root

boolean

Whether this entity is a root entity or a subsidiary.

business_id

string

The ID of the associated business object, if applicable.

user_id

string

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

creation_context

string

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

operating_address

object

Show operating_addres

string

Unique identifier for the operating address.

line_1

string

Street address line 1.

line_2

string

Street address line 2.

city

string

City.

state

string

State or province.

postal_code

string

Postal or zip code.

country

string

Country.

owner_id

string

The ID of the entity that owns this address.

owner_type

string

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

created

number

The timestamp when this address was created.

updated

number

The timestamp when this address was last updated.

business

object

The business-specific details for this entity.

Show business

string

Unique identifier for the business details object.

legal_name

string

The registered legal name of the business.

trade_name

string

The trading name or DBA of the business.

string

The contact email for the business.

phonenumber

string

The contact phone number for the business.

registration_number

string

The government-issued registration number for the business.

industry

string

The industry code or description for the business.

website

string

The website URL for the business.

type

string

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

description

string

A description of what the business does.

incorporation_meta

object

Additional details about the business’s incorporation.

Show incorporation_meta

year

number

The year the business was incorporated.

month

number

The month the business was incorporated.

country

string

The country where the business was incorporated.

state

string

The state or province where the business was incorporated.

created

number

The timestamp when these business details were created.

updated

number

The timestamp when these business details were last updated.

business_meta

object

Additional metadata related to the business entity.

Show business_meta

string

Unique identifier for the business meta object.

business_id

string

The ID of the associated business details object.

meta

object

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

Show meta

tax_id

string

The tax identification number for the business.

proof_of_address

string

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

incorporation_document

string

A URL to the incorporation document for the business.

mou_document

string

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

use_case

string

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

registration_number

string

The government-issued registration number for the business.

created

number

The timestamp when this business meta was created.

updated

number

The timestamp when this business meta was last updated.

business_officers

array

A list of the business officers associated with this entity.

Show business_officers

string

Unique identifier for the business officer record.

person_id

string

The ID of the person associated with this officer.

job_title

string

The job title of the officer within the business.

is_control_person

boolean

Whether this officer has significant control over the business.

is_beneficial_owner

boolean

Whether this officer is a beneficial owner of the business.

ownership_percentage

number

The percentage of ownership this officer has in the business.

business_id

string

The ID of the associated business details object.

created

number

The timestamp when this business officer record was created.

updated

number

The timestamp when this business officer record was last updated.

Get an entity

Retrieves an existing entity by ID.

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

Request parameters

entity_id

string

required

The ID of the entity to retrieve.

Response

Returns the entity object.

Response

{
  "id": "ent_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.

Documentation Index

​The Entity object

​Create an individual entity

​Request parameters

​Response

​Update an individual entity

​Request parameters

​Sample Response

​Response fields

​Create a business entity

​Request parameters

​Response

​Upload a KYC document

​Request parameters

​Response

​Submit for onboarding review

​Request parameters

​Response

​Update a business entity

​Request Parameters

​Response fields

​Get an entity

​Request parameters

​Response

​Entity statuses

The Entity object

Create an individual entity

Request parameters

Response

Update an individual entity

Request parameters

Sample Response

Response fields

Create a business entity

Request parameters

Response

Upload a KYC document

Request parameters

Response

Submit for onboarding review

Request parameters

Response

Update a business entity

Request Parameters

Response fields

Get an entity

Request parameters

Response

Entity statuses