Skip to content

Entity Onboarding

Entity Onboarding represents the KYC (Know Your Customer) data collected for an entity before enabling payment features like multi-currency accounts. The onboarding record holds business details, beneficial owners, addresses, identifiers, and supporting documents.

Entity Onboarding Object

{
  "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHlPbmJvYXJkaW5nLzE",
  "status": "draft",
  "primary_contact_email": "admin@acme.com",
  "primary_contact_mobile": "+1-555-987-6543",
  "primary_contact_mobile_country_code": "+1",
  "submitted_at": null,
  "approved_at": null,
  "created_at": "2025-10-20T10:30:00Z",
  "updated_at": "2025-10-20T10:30:00Z",
  "business_details": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQnVzaW5lc3NEZXRhaWwvMQ",
    "business_name": "Acme Corporation",
    "business_name_trading": "Acme Corp",
    "business_structure": "corporation",
    "business_start_date": "2020-01-15",
    "industry_category_code": "5411",
    "description_of_goods_services": "Software development and consulting services",
    "website_url": "https://acme.com",
    "contact_phone": "+1-555-123-4567",
    "state_of_incorporation": "DE",
    "created_at": "2025-10-20T10:30:00Z",
    "updated_at": "2025-10-20T10:30:00Z",
    "business_address": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQWRkcmVzcy8x",
      "address_type": "business",
      "line1": "123 Main Street",
      "line2": "Suite 400",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country_alpha2": "US",
      "created_at": "2025-10-20T10:30:00Z",
      "updated_at": "2025-10-20T10:30:00Z"
    },
    "registration_address": null,
    "business_identifiers": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQnVzaW5lc3NJZGVudGlmaWVyLzE",
        "identifier_type": "ein",
        "identifier_number": "12-3456789",
        "country_alpha2": "US",
        "created_at": "2025-10-20T10:30:00Z",
        "updated_at": "2025-10-20T10:30:00Z"
      }
    ]
  },
  "persons": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uLzE",
      "first_name": "John",
      "middle_name": null,
      "last_name": "Doe",
      "email": "john.doe@acme.com",
      "phone_number": "+1-555-123-4567",
      "date_of_birth": "1980-05-15",
      "nationality": "US",
      "job_title": "CEO",
      "roles": ["beneficial_owner", "director"],
      "created_at": "2025-10-20T10:30:00Z",
      "updated_at": "2025-10-20T10:30:00Z",
      "residential_address": {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQWRkcmVzcy8z",
        "address_type": "residential",
        "line1": "789 Oak Lane",
        "line2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postal_code": "94301",
        "country_alpha2": "US",
        "created_at": "2025-10-20T10:30:00Z",
        "updated_at": "2025-10-20T10:30:00Z"
      },
      "identifications": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uSWRlbnRpZmljYXRpb24vMQ",
          "identification_type": "tax_id",
          "identification_number": "***-**-6789",
          "issuing_country": "US",
          "effective_date": null,
          "expiration_date": null,
          "is_primary": true,
          "tax_id_type": "ssn",
          "created_at": "2025-10-20T10:30:00Z",
          "updated_at": "2025-10-20T10:30:00Z"
        }
      ]
    }
  ]
}

Attributes

Attribute Type Description
id string Unique identifier for the onboarding record
status string Current onboarding status (see Onboarding Status)
primary_contact_email string/null Primary contact email for the onboarding process
primary_contact_mobile string/null Primary contact phone number
primary_contact_mobile_country_code string/null Country calling code (e.g., "+1")
submitted_at string/null ISO 8601 timestamp when onboarding was submitted for review
approved_at string/null ISO 8601 timestamp when onboarding was approved
created_at string ISO 8601 timestamp when the record was created
updated_at string ISO 8601 timestamp when the record was last updated
business_details object/null Business details for the entity (see Business Details)
persons array Array of persons associated with the entity (see Persons)

Onboarding Status

Status Description
draft Onboarding data is being collected. This is the initial state.
submitted Onboarding has been submitted to the payment provider for review.
approved Onboarding has been reviewed and approved by the payment provider.
rejected Onboarding was rejected by the payment provider.

Status Transitions

draftsubmittedaction_requiredcomplete User submits onboarding Application approved Additional info needed User provides info
draftsubmittedaction_requiredcomplete User submits onboarding Application approved Additional info needed User provides info
  • draft → submitted — when the user submits the onboarding form
  • submitted → complete — when the application is approved
  • submitted → action_required — when additional information is needed
  • action_required → submitted — when the user provides the requested information

Nested Objects

Business Details

Business details contain the legal and operational information about the entity.

Attribute Type Description
id string Unique identifier
business_name string/null Legal business name (max 255 characters)
business_name_trading string/null Trading name / DBA
business_structure string/null Legal structure (see Business Structure)
business_start_date string/null Date the business started (YYYY-MM-DD)
industry_category_code string/null Industry classification code (e.g., NAICS)
description_of_goods_services string/null Description of products or services
website_url string/null Business website URL
contact_phone string/null Business contact phone number
state_of_incorporation string/null State/province of incorporation
created_at string ISO 8601 creation timestamp
updated_at string ISO 8601 last update timestamp
business_address object/null Business office address (see Address)
registration_address object/null Legal registration address (see Address)
business_identifiers array Array of business identifiers (see Business Identifier)

Business Structure

Value Description
corporation Corporation
llc Limited Liability Company
llp Limited Liability Partnership
partnership Partnership
general_partnership General Partnership
limited_partnership Limited Partnership
sole_proprietor Sole Proprietorship
trust Trust
company Company (general)
other Other structure

Address

Addresses are used for business locations, registration addresses, and residential addresses of persons.

Attribute Type Description
id string Unique identifier
address_type string Type: business, registration, or residential
line1 string/null Street address line 1 (max 255 characters)
line2 string/null Street address line 2 (max 255 characters)
city string/null City (max 100 characters)
state string/null State or province (max 100 characters)
postal_code string/null Postal/ZIP code (max 20 characters)
country_alpha2 string/null ISO 3166-1 alpha-2 country code (e.g., "US")
created_at string ISO 8601 creation timestamp
updated_at string ISO 8601 last update timestamp

Business Identifier

Business identifiers represent tax and registration numbers for the entity.

Attribute Type Description
id string Unique identifier
identifier_type string Type of identifier (see Identifier Types)
identifier_number string The identifier number (max 100 characters)
country_alpha2 string/null ISO 3166-1 alpha-2 country code
created_at string ISO 8601 creation timestamp
updated_at string ISO 8601 last update timestamp

Identifier Types

Type Description
ein Employer Identification Number (US)
vat Value Added Tax Number
brn Business Registration Number
ssn Social Security Number

Persons

Persons represent individuals associated with the entity — beneficial owners, directors, and authorized persons.

Attribute Type Description
id string Unique identifier
first_name string/null First name (max 100 characters)
middle_name string/null Middle name
last_name string/null Last name (max 100 characters)
email string/null Email address
phone_number string/null Phone number
date_of_birth string/null Date of birth (YYYY-MM-DD)
nationality string/null ISO 3166-1 alpha-2 country code
job_title string/null Job title or position
roles array Array of role strings (see Person Roles)
created_at string ISO 8601 creation timestamp
updated_at string ISO 8601 last update timestamp
residential_address object/null Person's residential address (see Address)
identifications array Array of identification documents (see Person Identification)

Person Roles

Role Description
beneficial_owner Person who owns more than 25% of the entity
director Board member or director
authorized_person Person authorized to act on behalf of the company
controlling_person Person with significant control over the entity
legal_representative Legal representative of the entity

Person Identification

Identification documents for persons, such as passports or tax IDs.

Attribute Type Description
id string Unique identifier
identification_type string Type of identification (see Identification Types)
identification_number string The identification number (may be masked for security)
issuing_country string/null ISO 3166-1 alpha-2 country code of issuing authority
effective_date string/null Date the document became valid (YYYY-MM-DD)
expiration_date string/null Document expiration date (YYYY-MM-DD)
is_primary boolean Whether this is the primary identification document
tax_id_type string/null Tax ID subtype, only when identification_type is tax_id (see Tax ID Types)
created_at string ISO 8601 creation timestamp
updated_at string ISO 8601 last update timestamp

Identification Types

Type Description
passport Passport
drivers_license Driver's License
personal_id Personal ID Card
tax_id Tax Identification Document

Tax ID Types

Only applicable when identification_type is tax_id:

Type Description
ssn Social Security Number (US)
itin Individual Taxpayer Identification Number (US)

Attachments

Supporting documents uploaded for onboarding verification. Attachments can be associated with the onboarding record itself, business details, persons, or person identifications.

Attribute Type Description
id string Unique identifier
category string Document category (see Attachment Categories)
document_type string/null Type of document (see Document Types)
tag string/null Provider-specific tag for categorization
side string/null For identity documents: front or back
description string/null Human-readable description
original_filename string Original uploaded filename
content_type string MIME type of the file
file_size integer File size in bytes
upload_status string Upload status: pending, uploading, uploaded, failed
attachable_type string Type of parent record (see Attachable Types)
attachable_id string ID of the parent record
created_at string ISO 8601 creation timestamp
updated_at string ISO 8601 last update timestamp

Attachment Categories

Category Description
business_document Company-related documents (incorporation certificates, etc.)
identity_document Identity verification documents (passports, IDs)
person_document Person-related supporting documents
additional_file Other supporting files

Document Types

Type Description
passport Passport
drivers_license Driver's License
personal_id Personal ID Card
tax_id Tax Identification Document
certificate_of_incorporation Certificate of Incorporation
ownership_structure Ownership Structure Document
proof_of_address Proof of Address
bank_statement Bank Statement
other Other Document Type

Attachable Types

Type Description
entity_onboarding Attach to the main onboarding record
business_detail Attach to business details
person Attach to a specific person
identification Attach to a person's identification document

File Constraints

  • Supported formats: PDF, JPEG, PNG, GIF, TIFF
  • Maximum file size: 10 MB

Data Model Relationships

The following diagram shows how onboarding objects relate to each other:

EntityOnboardingBusinessDetailsAddress (business)Address (registration)BusinessIdentifier[]Person[]Address (residential)PersonIdentification[]Attachment[] has one has many has many has one has one has many has many has one has many has many has many (front/back)
EntityOnboardingBusinessDetailsAddress (business)Address (registration)BusinessIdentifier[]Person[]Address (residential)PersonIdentification[]Attachment[] has one has many has many has one has one has many has many has one has many has many has many (front/back)

Available Operations

  • Get Onboarding - Retrieve onboarding data for an entity
  • Update Onboarding - Create or update onboarding data (business details, addresses, identifiers, primary contact)
  • List Persons - Retrieve all persons for an entity's onboarding
  • Create Person - Add a beneficial owner, director, or authorized person
  • Get Person - Retrieve a specific person
  • Update Person - Update person details
  • Delete Person - Remove a person
  • List Attachments - Retrieve all onboarding attachments
  • Create Attachment - Upload a supporting document
  • Delete Attachment - Remove an attachment

Onboarding Data and Multi-Currency

Providing onboarding data and documents via the API before enabling multi-currency:

  • Pre-fills business information on the hosted onboarding page
  • Automatically submits documents for verification
  • Reduces friction and completion time for the end user
  • Entities with an active payment integration cannot have their onboarding data updated

Usage Notes

  • One Per Entity - Each entity has at most one onboarding record
  • Auto-Created - The onboarding record is created automatically when you first update onboarding data
  • Identifier Replacement - Submitting business_identifiers replaces all existing identifiers (not a merge)
  • Identification Replacement - Submitting identifications for a person replaces all existing identifications
  • Attachment Sync - Uploaded documents are automatically synced to the payment provider when multi-currency is enabled
  • Immutable After Activation - Entities with an active payment integration cannot have their onboarding data modified

For detailed API endpoints and request/response examples, see the Entity Onboarding API Reference.