An entity is the foundational object in Nuvion. Everything — accounts, transactions, payouts — belongs to an entity. Before an entity can hold funds or move money, they must complete verification through Nuvion’s onboarding flow.
Entity types Type Description individualA natural person on your platform businessA registered business or legal entity
Entity statuses Entities move through a defined lifecycle from creation to activation.
Status Description incompleteEntity has been created but is missing required information or documents pendingEntity has been submitted for review and verification is underway approvedVerification is complete — the entity can create accounts and transact rejectedVerification failed — rejection reasons are provided and the entity may resubmit suspendedEntity has been suspended — contact Nuvion support
incomplete → pending → approved ↓ rejected → (resubmit) → pending
Account creation and transactions are only available when an entity has approved status.
The entity object The full response schema is pending confirmation. The fields below reflect what is currently known. This section will be updated.
{ "id" : "ent_01HXYZ1234ABCD" , "object" : "entity" , "type" : "business" , "status" : "approved" , "pending_verification_requirements" : [], "created_at" : "2026-01-01T10:00:00Z" , "updated_at" : "2026-01-01T10:30:00Z" }
Unique identifier for the entity. ULID format.
The entity type. Either individual or business.
The entity’s current verification status. One of incomplete, pending, approved, rejected, suspended.
pending_verification_requirements
A list of items still required before the entity can be submitted for verification. Empty when the entity is ready to submit.
ISO 8601 timestamp of when the entity was created.
ISO 8601 timestamp of the last update to the entity.
Creating a business entity Business entity creation is a three-step process: create the entity, upload documents, then submit for verification.
Step 1: Create the entity curl -X POST https://api.nuvion.dev/business-entities \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Technologies Ltd", "business": { "legal_name": "Acme Technologies Limited", "trade_name": "Acme Tech", "industry": "Technology", "email": "finance@acmetech.com", "website": "https://acmetech.com", "type": "llc", "description": "A B2B SaaS platform for logistics management.", "registration_number": "EIN-47-1234567", "phonenumber": "+12125550100", "incorporation_meta": { "year": 2019, "month": 4, "country": "US", "state": "Delaware" } }, "address": { "line_1": "350 Fifth Avenue", "city": "New York", "state": "New York", "postal_code": "10118", "country_code": "US" }, "operating_address": { "line_1": "350 Fifth Avenue", "city": "New York", "state": "New York", "postal_code": "10118", "country_code": "US" }, "business_officers": [ { "job_title": "Chief Executive Officer", "is_control_person": true, "is_beneficial_owner": true, "ownership_percentage": 60, "person": { "first_name": "Alex", "last_name": "Johnson", "date_of_birth": "1985-06-15", "email": "alex.johnson@acmetech.com", "nationality": "US", "gender": "m", "identification": { "document": { "type": "international_passport", "number": "P123456789", "issue_date": "2020-01-10", "expiry_date": "2030-01-09", "issuing_country": "US" } }, "address": { "line_1": "210 West 77th Street", "city": "New York", "state": "New York", "postal_code": "10024", "country_code": "US" } } } ] }'
Request fields A display name for the entity. 1–255 characters.
Core business information. The entity’s registered legal name. 1–255 characters.
Trading name or DBA, if different from the legal name. Max 255 characters.
The industry the business operates in. 1–100 characters.
Business contact email address.
Legal structure of the business. e.g. llc, corporation, partnership, sole_proprietorship.
A description of what the business does. 1–1000 characters.
Government-issued business registration number. 1–255 characters.
Business phone number including country code. 10–14 characters.
Details of when and where the business was incorporated. Show incorporation_meta fields
Month of incorporation. 1–12.
ISO 3166-1 alpha-2 country code of incorporation. e.g. NG, US.
State or province of incorporation. 1–100 characters.
Registered address of the business. Street address line 1. 1–255 characters.
Street address line 2. Max 255 characters.
Street address line 3. Max 255 characters.
State or province. 1–100 characters.
Postal or ZIP code. 1–20 characters.
ISO 3166-1 alpha-2 country code. e.g. NG, US, GB.
Additional address metadata.
The address where the business physically operates, if different from the registered address. Same structure as address.
The individuals associated with the business. At least one officer is required. Show business_officers fields
The officer’s title within the organization. 1–100 characters.
Whether this person has significant management control over the business.
Whether this person owns 25% or more of the business.
The officer’s ownership stake. 0–100.
Additional compliance and business metadata. Government-issued registration number, if not provided in the business object.
Tax identification number.
Estimated annual revenue.
monthly_transaction_value
Expected monthly transaction volume.
Expected number of monthly payments.
Maximum single transfer amount.
Description of the business’s customer base.
Channels through which the business sells (e.g. online, in-person).
Primary source of funds for the business.
Reference ID from a liveness or biometric check.
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.
ISO 3166-1 alpha-2 country code. e.g. NG, GH, US.
m for male, f for female.
Identity verification documents for this person. Show identification fields
Government-issued identity document. Must be from a non-sanctioned country. Document type. One of international_passport, drivers_license, national_id.
Date the document was issued. Format: YYYY-MM-DD.
Date the document expires. Format: YYYY-MM-DD.
ISO 3166-1 alpha-2 country code of the issuing authority.
Name of the authority that issued the document.
Additional fields for country-specific document types. Show type_specific fields
Subtype for national ID documents. One of BVN, SSN, NIN.
Address verification document. Show proof_of_address fields
One of utility_bill, bank_statement.
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 keyAccepted formats Certificate of Incorporation certificate_of_incorporationPDF Memorandum of Association memorandum_of_associationPDF, DOCX Proof of Address proof_of_addressPDF, JPG, JPEG, PNG Tax Verification Document tax_verificationPDF
Required per officer Document keyGovernment-issued ID identityProof of address proof_of_address
curl -X POST https://api.nuvion.dev/documents \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "entity_id": "ent_01HXYZ1234ABCD", "key": "certificate_of_incorporation", "description": "Certificate of Incorporation for Acme Technologies Limited", "file": "base64_encoded_content_here", "meta": { "file_type": "application/pdf" } }'
To link a document to a specific officer, include link_to_identity with the officer’s person_id:
curl -X POST https://api.nuvion.dev/documents \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "entity_id": "ent_01HXYZ1234ABCD", "key": "identity", "description": "International passport for Alex Johnson", "file": "base64_encoded_front_here", "file_back": "base64_encoded_back_here", "meta": { "file_type": "application/pdf" }, "link_to_identity": { "person_id": "per_01HXYZ1234ABCD" } }'
Request fields ULID of the entity to attach the document to. Required when uploading via the API.
Base64-encoded file content. Accepted formats: PDF, JPG, JPEG, PNG, DOC, DOCX.
Base64-encoded back side of the document. Use for identity documents that have information on both sides.
A human-readable description of the document. 1–500 characters.
The document type. One of identity, proof_of_address, tax_verification, certificate_of_incorporation, memorandum_of_association.
Additional document metadata. MIME type of the document. e.g. application/pdf, image/jpeg.
Links this document to a specific business officer. Required when uploading identity or address documents for an officer. Show link_to_identity fields
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. Check pending_verification_requirements on the entity first — it will be empty when the entity is ready to submit.
curl -X POST https://api.nuvion.dev/onboarding-submissions \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "entity_id": "ent_01HXYZ1234ABCD" }'
The entity status moves to pending. Nuvion’s compliance team reviews the submission and updates the status to approved or rejected.
Don’t poll GET /entities/:id to check status. Listen for the entities.updated webhook event instead.
Resubmitting after rejection If an entity is rejected, the rejection response includes the reasons. Correct the relevant information or documents and call POST /onboarding-submissions again.
The full resubmission flow is pending confirmation with engineering. This section will be updated.
Creating an individual entity Individual entities represent natural persons on your platform. Onboarding follows the same three-step flow as business entities: create the entity, upload identity documents, then submit for verification.
Step 1: Create the entity curl -X POST https://api.nuvion.dev/individual-entities \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "name": "Alex Johnson", "person": { "first_name": "Alex", "last_name": "Johnson", "date_of_birth": "1990-04-12", "email": "alex.johnson@example.com", "nationality": "US", "gender": "m", "phonenumber": "+12125550198" }, "address": { "line_1": "210 West 77th Street", "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" } }, "meta": { "funding_source": "salary", "monthly_transaction_value": "5000" } }'
The response includes an entity_id and a person_id. You will need the person_id to link identity documents to this individual in Step 2.
Request fields A display name for the entity. 1–255 characters.
Personal details for the individual. ISO 3166-1 alpha-2 country code. e.g. US, GB, CA.
m for male, f for female.
Phone number including country code. 10–14 characters.
Residential address of the individual. Street address line 1. 1–255 characters.
Street address line 2. Max 255 characters.
Street address line 3. Max 255 characters.
State or province. 1–100 characters.
Postal or ZIP code. 1–20 characters.
ISO 3166-1 alpha-2 country code. e.g. US, GB, CA.
Additional address metadata.
Identity and address verification documents. Show identification fields
Government-issued identity document. Document type. One of international_passport, drivers_license, national_id.
Date the document was issued. Format: YYYY-MM-DD.
Date the document expires. Format: YYYY-MM-DD.
ISO 3166-1 alpha-2 country code of the issuing authority.
Name of the authority that issued the document.
Additional fields for country-specific document types. Show type_specific fields
Subtype for national ID documents. One of BVN, SSN, NIN.
Address verification document. Show proof_of_address fields
One of utility_bill, bank_statement.
Business context for the individual, if applicable (e.g. a sole trader or freelancer). Trading name. 1–100 characters.
Description of the business activity. 1–200 characters.
Business category code. 1–100 characters.
Business sub-category code. 1–100 characters.
URL of a liveness or biometric report for this individual.
Additional compliance and risk metadata. Tax identification number.
Expected number of monthly payments.
monthly_transaction_value
Expected monthly transaction volume.
Maximum single transfer amount.
Estimated annual income or revenue.
Description of the individual’s customer base, if applicable.
Primary source of funds. e.g. salary, business_income, investments.
The ID of a parent entity, if this individual is associated with a business entity. 26-character ULID.
Description of the relationship to the parent entity. 1–100 characters.
Step 2: Upload documents Upload two required documents for the individual via POST /documents. Documents must be base64-encoded.
Document keyAccepted types Government-issued ID identityPassport, driver’s license, national ID Proof of address addressUtility bill, bank statement, or government correspondence — must be dated within 3 months
Identity document
Proof of address
curl -X POST https://api.nuvion.dev/documents \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "entity_id": "ent_01HXYZ1234ABCD", "key": "identity", "description": "International passport for Alex Johnson", "file": "base64_encoded_front_here", "file_back": "base64_encoded_back_here", "meta": { "file_type": "application/pdf" }, "link_to_identity": { "person_id": "per_01HXYZ1234ABCD" } }'
Step 3: Submit for verification Once both documents are uploaded, submit the entity for review. Check pending_verification_requirements first — it will be empty when the entity is ready to submit.
curl -X POST https://api.nuvion.dev/onboarding-submissions \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "entity_id": "ent_01HXYZ1234ABCD" }'
The entity status moves to pending. Listen for the entities.updated webhook to be notified when verification completes.
Webhooks Nuvion emits events when entity state changes. Subscribe to these to keep your platform in sync without polling.
Event When it fires entities.updatedEntity status changes (e.g. pending → approved)
Full event payload schemas are pending confirmation with engineering. This section will be updated.
What’s next
Create an account Issue a multi-currency account for an approved entity.
Entities API reference Full endpoint documentation for creating and managing entities.
Webhooks Set up webhook listeners for entity and document events.
