Skip to main content
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

​
id
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.
​
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.
​
email
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.

​
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.
​
email
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.
​
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
file
required
The document file. Accepted formats: PDF, JPG, PNG. Maximum file size: 10 MB.

​
Response

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
}

​
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

StatusDescription
pendingEntity created or submitted, awaiting review.
approvedKYC/KYB passed — accounts can be created for this entity.
rejectedReview failed — the entity cannot proceed. Check the rejection reason returned by the webhook.
suspendedAccount access temporarily restricted. Contact support to resolve.