Skip to main content
This guide builds on the concept of entities.
Nuvion requires you to have a proper KYC process if you’re moving customer funds. This guide walks you through how to meet some compliance requirements. Entities are required before you can create accounts or move money. Required fields for creating these entities depend on your use case, product, and customer type. Nuvion supports two types of entities:
  1. Individual Entity
  2. Business Entity

Individual Entity

To create an individual entity, you’ll need to collect personal information and an ID document from your user. See the full list of requirements here.
curl --location 'https://api.nuvion.dev/individual-entities' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{$NUVION_API_KEY}}' \
--data-raw '{
    "name": "John Doe",
    "person": {
        "first_name": "John",
        "last_name": "Doe",
        "middle_name": "Robert",
        "date_of_birth": "1990-05-15",
        "email": "[email protected]",
        "nationality": "US",
        "gender": "m"
    },
    "address": {
        "line_1": "123 Main Street",
        "line_2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country_code": "US"
    },
    "identification": {
        "national_id": {
            "type": "SSN",
            "value": "123-45-6789"
        },
        "drivers_license": {
            "number": "DL12345678",
            "issuing_country": "US",
            "issue_date": "2020-01-15",
            "expiry_date": "2028-01-14"
        }
    },
    "parent_entity": "01K5EEGEXW2HX09DJPXZM4S3WD",
    "parent_relationship": "employee"
}'

Business Entity

For corporate or business users, collect business information such as business name, registration (EIN or local equivalent) and address.
curl --location 'https://api.nuvion.dev/business-entities' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{$NUVION_API_KEY}}' \
--data-raw '{
    "name": "Acme Corporation",
    "parent_relationship": "subsidiary",
    "business": {
        "website": "https://acmecorp.com",
        "trade_name": "Acme",
        "type": "LLC",
        "industry": "Technology",
        "legal_name": "Acme Corporation LLC",
        "registration_number": "REG123456789",
        "description": "A leading provider of innovative technology solutions",
        "incorporation_meta": {
            "year": 2020,
            "month": 4,
            "country": "US",
            "state": "California"
        }
    },
    "address": {
        "line_1": "123 Tech Drive",
        "line_2": "Suite 500",
        "country_code": "US",
        "city": "San Francisco",
        "state": "California",
        "postal_code": "94105"
    },
    "business_officers": [
        {
            "is_control_person": true,
            "is_beneficial_owner": true,
            "ownership_percentage": 60,
            "job_title": "Chief Executive Officer",
            "person": {
                "first_name": "Jane",
                "last_name": "Smith",
                "middle_name": "Marie",
                "date_of_birth": "1985-05-15",
                "email": "[email protected]",
                "nationality": "US",
                "gender": "f",
                "address": {
                    "line_1": "456 Oak Street",
                    "line_2": "Apt 303",
                    "country_code": "US",
                    "city": "San Francisco",
                    "state": "California",
                    "postal_code": "94107"
                },
                "identification": {
                    "drivers_license": {
                        "number": "DL123456789",
                        "issuing_country": "US",
                        "issue_date": "2018-01-15",
                        "expiry_date": "2026-01-14",
                        "urls": {
                            "main": "https://storage.example.com/documents/dl-front-123.jpg",
                            "back": "https://storage.example.com/documents/dl-back-123.jpg"
                        }
                    }
                }
            }
        },
        {
            "is_control_person": false,
            "is_beneficial_owner": true,
            "ownership_percentage": 40,
            "job_title": "Chief Financial Officer",
            "person": {
                "first_name": "Michael",
                "last_name": "Johnson",
                "date_of_birth": "1982-09-23",
                "email": "[email protected]",
                "nationality": "US",
                "gender": "m",
                "address": {
                    "line_1": "789 Pine Avenue",
                    "country_code": "US",
                    "city": "San Francisco",
                    "state": "California",
                    "postal_code": "94109"
                },
                "identification": {
                    "national_id": {
                        "type": "SSN",
                        "value": "123-45-6789",
                        "urls": {
                            "main": "https://storage.example.com/documents/ssn-123.jpg"
                        }
                    }
                }
            }
        }
    ]
}'
See the full list of required fields for creating a business entity here.

Account structure

The easiest setup is to create individual accounts per customer. This eliminates the need for your own ledger and keeps ownership flexible. Accounts are created synchronously, and you can create as many as you need. If you prefer, you can run one business account for your app, but then you’ll need to track funds by customer. Either way, unique account numbers are available for monitoring incoming payments.
Every account must be linked to an Entity.