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.

string

individual or business.

string

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

object

Identity details. Shape depends on type.

Show Individual profile fields

string

Legal first name.

string

Legal last name.

string

Contact email address.

string

Date of birth in YYYY-MM-DD format.

string

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

Show Business profile fields

string

Full registered legal name of the business.

string

Business contact email address.

string

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

string

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

object

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

number

Unix timestamp in milliseconds when the entity was created.

number

Unix timestamp in milliseconds when the entity was last updated.

Example

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

Create an individual entity

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

curl -X POST https://api.nuvion.dev/individual-entities \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Johnson",
    "person": {
      "first_name": "Alex",
      "last_name": "Johnson",
      "Middle_name": "M",
      "date_of_birth": "1990-04-12",
      "email": "alex.johnson@example.com",
      "nationality": "US",
      "gender": "m",
      "phonenumber": "+12125550198",
      "bvn": "23487892834",
      "nin": "25856743645",
      "ssn": "123-45-6789"
    },
    "address": {
      "line_1": "210 West 77th Street",
      "line_2": "Apt 4B",
      "line_3": "Suite 5C",
      "city": "New York",
      "state": "New York",
      "postal_code": "10024",
      "country_code": "US"
    },
    "identification": {
      "document": {
        "type": "international_passport",
        "number": "P123456789",
        "issue_date": "2020-01-10",
        "expiry_date": "2030-01-09",
        "issuing_country": "US",
        "issuing_authority": "US Department of State",
        "document_id": "01HXYZ1234ABCD",
        "type_specific": {
          "id_subtype": "SSN"
        }
      },
      "proof_of_address": {
        "type": "utility_bill",
        "document_id": "01HXYZ5678EFGH"
      }
    },
    "meta": {
      "funding_source": "salary",
      "monthly_transaction_value": "5000",
      "tax_id": "TAX-1234567890",
      "annual_turnover": "60000",
      "customer_types": "individual",
      "monthly_payments_count": "10",
      "max_transfer_amount": "10000",
      "sales_channels": "My own website",
    }
  }'

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.

Response

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

Response

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

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

string

The name of the individual entity.

object

The profile details of the individual entity.

Show person fields

string

Legal first name of the individual.

string

Legal last name of the individual.

string

Contact email address. Must be a valid email format.

string

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

string

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

string

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

string

The individual’s phone number.

object

The address of the individual entity.

Show address fields

string

Street address line 1.

string

Street address line 2.

string

Street address line 3.

string

Additional address metadata.

string

City.

string

State/province/region.

string

Postal or ZIP code.

string

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

object

Show business fields

string

Full registered legal name of the business.

string

Business contact name

string

Business liveness report url.

string

Business description.

string

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

string

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

object

The identification details of the individual entity.

Show identification fields

object

The identification document details.

Show document fields

string

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

string

The identification document number.

string

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

string

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

string

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

string

The authority that issued the identification document.

string

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

object

Additional fields specific to the type of identification document.

Show type_specific fields

object

The proof of address document details.

Show proof_of_address fields

string

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

string

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

string

The parent entity. This links the individual to the to the parent entity for hierarchical 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

string

A message describing the result of the update operation.

string

The status of the update operation.

object

The updated entity data.

Show data

object

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

array

The updated address object for the individual entity.

array

The updated entity object for the individual entity.

array

The updated person object for the individual entity.

array

The updated identification object for the individual entity.

object

The updated address details of the individual entity.

Show address fields

string

Street address line 1.

string

Street address line 2.

string

Street address line 3.

string

Additional address metadata.

string

City.

string

State/province/region.

string

Postal or ZIP code.

string

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

string

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

string

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

number

Unix timestamp in milliseconds when the address was created.

number

Unix timestamp in milliseconds when the address was last updated.

object

The updated entity details of the individual entity.

Show entity fields

string

Unique entity identifier. Prefix: ent_.

string

individual or business.

string

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

string

The name of the individual entity.

boolean

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

string

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

string

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

number

Unix timestamp in milliseconds when the entity was created.

number

Unix timestamp in milliseconds when the entity was last updated.

object

The updated person details of the individual entity.

Show person fields

string

Legal first name of the individual.

string

Legal last name of the individual.

string

Middle name of the individual.

string

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

string

Contact email address. Must be a valid email format.

string

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

string

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

boolean

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

string

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

string

The individual’s phone number.

number

Unix timestamp in milliseconds when the person profile was created.

number

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

object

The updated identification details of the individual entity.

Show identification fields

string

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

number

Unix timestamp in milliseconds when the identification details were created.

number

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

object

The updated proof of address document details.

Show proof_of_address fields

string

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

string

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

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 '{
    "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.

Response

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

Response

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

Upload a KYC document

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

curl -X POST https://api.nuvion.dev/documents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ1234ABCD",
    "key": "identity",
    "description": "International passport for Alex Johnson",
    "file": "base64_encoded_front_here",
    "file_back": "base64_encoded_back_here",
    "meta": {
      "file_type": "application/pdf"
    },
    "link_to_identity": {
      "person_id": "per_01HXYZ1234ABCD"
    }
  }'

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

Request parameters

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

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

Request parameters

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

string

The name of the business entity.

object

The profile details of the business entity.

Show business fields

string

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

string

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

string

The business’s website URL.

string

A description of the business.

string

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

string

The business’s phone number.

string

The business’s contact email address.

string

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

object

Additional details about the business’s incorporation.

Show incorporation_meta fields

string

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

string

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

string

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

string

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

object

The registered address of the business.

Show address fields

string

Street address line 1.

string

Street address line 2.

string

Street address line 3.

string

Additional address metadata.

string

City.

string

State or province.

string

Postal or ZIP code.

string

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

object

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

Show operating_address fields

string

Street address line 1.

string

Street address line 2.

string

Street address line 3.

string

Additional address metadata.

string

City.

string

State or province.

string

Postal or ZIP code.

string

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

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.

string

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

string

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

boolean

Whether the officer is a control person for the business.

boolean

Whether the officer is a beneficial owner of the business.

number

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

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.

object

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

Show meta fields

string

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

string

The business’s tax identification number.

string

The ID of a liveness check report to link to the business entity for KYB review.

number

The number of payments processed by the business in the past month to provide additional context for KYB review.

number

The total value of payments processed by the business in the past month to provide additional context for KYB review.

number

The maximum amount the business expects to transfer in a single payment to provide additional context for KYB review.

number

The annual turnover of the business to provide additional context for KYB review.

string

The types of customers the business serves (e.g. “individuals”, “other businesses”, “nonprofits”, etc.) to provide additional context for KYB review.

string

The primary sales channel for the business (e.g. “online”, “in-person”, “both”) to provide additional context for KYB review.

string

The primary funding sources for the business (e.g. “bank account”, “credit card”, “both”) to provide additional context for KYB review.

string

The parent entity ID to link to for hierarchical 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
            }
        ]
    }
}

string

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

string

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

object

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

Show data

object

The list of changes applies

Show changes_applied

array

List of meta fields that were updated.

array

List of entity fields that were updated.

array

List of address fields that were updated.

array

List of officers that were added.

array

List of business fields that were updated.

aray

List of officers that were removed.

array

List of officers that were updated.

object

The entity’s registered address object.

Show address

string

Unique identifier for the address.

string

Street address line 1.

string

Street address line 2.

string

City.

string

State or province.

string

Postal or zip code.

string

Country.

object

The main entity object with core details and status.

Show entity

string

Unique identifier for the entity.

string

The entity type. Either individual or business.

string

The entity’s current verification status.

string

The display name of the entity.

boolean

Whether this entity is a root entity or a subsidiary.

string

The ID of the associated business object, if applicable.

string

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

string

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

object

Show operating_addres

string

Unique identifier for the operating address.

string

Street address line 1.

string

Street address line 2.

string

City.

string

State or province.

string

Postal or zip code.

string

Country.

string

The ID of the entity that owns this address.

string

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

number

The timestamp when this address was created.

number

The timestamp when this address was last updated.

object

The business-specific details for this entity.

Show business

string

Unique identifier for the business details object.

string

The registered legal name of the business.

string

The trading name or DBA of the business.

string

The contact email for the business.

string

The contact phone number for the business.

string

The government-issued registration number for the business.

string

The industry code or description for the business.

string

The website URL for the business.

string

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

string

A description of what the business does.

object

Additional details about the business’s incorporation.

Show incorporation_meta

number

The year the business was incorporated.

number

The month the business was incorporated.

string

The country where the business was incorporated.

string

The state or province where the business was incorporated.

number

The timestamp when these business details were created.

number

The timestamp when these business details were last updated.

object

Additional metadata related to the business entity.

Show business_meta

string

Unique identifier for the business meta object.

string

The ID of the associated business details object.

object

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

Show meta

string

The tax identification number for the business.

string

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

string

A URL to the incorporation document for the business.

string

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

string

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

string

The government-issued registration number for the business.

number

The timestamp when this business meta was created.

number

The timestamp when this business meta was last updated.

array

A list of the business officers associated with this entity.

Show business_officers

string

Unique identifier for the business officer record.

string

The ID of the person associated with this officer.

string

The job title of the officer within the business.

boolean

Whether this officer has significant control over the business.

boolean

Whether this officer is a beneficial owner of the business.

number

The percentage of ownership this officer has in the business.

string

The ID of the associated business details object.

number

The timestamp when this business officer record was created.

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/01HXYZ1234ABCD \
  -H "Authorization: Bearer $NUVION_API_KEY"

Request parameters

string

required

The ID of the entity to retrieve.

Response

Returns the entity object.

Response

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

Entity statuses

Status	Description
`pending`	Entity created or submitted, awaiting review.
`approved`	KYC/KYB passed — accounts can be created for this entity.
`rejected`	Review failed — the entity cannot proceed. Check the rejection reason returned by the webhook.
`suspended`	Account access temporarily restricted. Contact support to resolve.

​The Entity object

​Create an individual entity

Request fields

​Response

​Update an individual entity

​Request parameters

​Sample Response

​Response fields

​Create a business entity

​Request fields

​Person object

​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

Response

Update an individual entity

Request parameters

Sample Response

Response fields

Create a business entity

Request fields

Person object

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