Create business customer

POST /v1/customers/business

Creates a business customer. Additional data (shareholders, documents) is added via separate endpoints.

For comprehensive KYB documentation, see Business Onboarding.

Required Fields

Field	Type	Description
`firstName`	`string`	First name of primary contact
`lastName`	`string`	Last name of primary contact
`email`	`string`	Email address
`entityName`	`string`	Legal entity name
`jurisdiction`	`string`	Country of jurisdiction (ISO 3166-1 alpha-2)

Optional Fields

Field	Type	Description
`middleName`	`string`	Middle name
`birthDate`	`string`	Birth date (YYYY-MM-DD)
`phone`	`string`	Phone number
`entityType`	`string`	Entity type (llc, corporation, dao, foundation, etc.)
`entityTypeDescription`	`string`	Custom entity type description
`tradeName`	`string`	DBA / trading name
`registrationNumber`	`string`	Company registration number
`incorporationDate`	`string`	Date of incorporation (YYYY-MM-DD)
`taxNumber`	`string`	Tax identification number
`businessDescription`	`string`	Description of business activities
`businessType`	`string`	Industry type
`businessTypeDescription`	`string`	Custom business type description
`websites`	`string[]`	Company website URLs
`phoneNumber`	`string`	Business phone number
`addressCountry`	`string`	Country (ISO 3166-1 alpha-2)
`streetAddress`	`string`	Street address
`addressLine2`	`string`	Address line 2
`city`	`string`	City
`state`	`string`	State/Province
`zip`	`string`	Postal/ZIP code
`sourceOfFunds`	`string`	Source of funds
`sourceOfFundDescription`	`string`	Custom source description
`expectedMonthlyVolumeUsd`	`number`	Expected monthly volume in USD
`purposeOfFunds`	`string`	Purpose of funds
`purposeOfFundsDescription`	`string`	Custom purpose description
`flowOfFundsDescription`	`string`	Flow of funds description
`sanctionedCountryOperations`	`boolean`	Operations in sanctioned countries
`highRiskActivities`	`string[]`	High-risk activities
`operatingCountries`	`string[]`	Countries of operation (ISO 3166-1 alpha-2)
`handlesCustomerFunds`	`boolean`	Handles customer funds
`complianceScreeningDescription`	`string`	Compliance screening procedures
`estimatedAnnualRevenue`	`number`	Estimated annual revenue in USD

Business Documents

POST /v1/customers/business/:id/documents

Creates a new document. Returns 409 if document of same type exists.

Request:

{
  "type": "certificate_of_incorporation",
  "base64": "JVBERi0xLjQKJe..."
}

Response 201:

{
  "id": "bizdoc_xxx",
  "type": "certificate_of_incorporation",
  "status": "pending",
  "createdAt": "2026-02-04T15:45:52.175Z",
  "updatedAt": "2026-02-04T15:45:52.175Z"
}

Response 409:

{
  "message": "Document of type 'certificate_of_incorporation' already exists for this customer. Use PUT to replace it."
}

PUT /v1/customers/business/:id/documents

Replaces an existing document. Returns 404 if document not found.

Request:

{
  "type": "certificate_of_incorporation",
  "base64": "JVBERi0xLjQKJe..."
}

Response 200:

{
  "id": "bizdoc_xxx",
  "type": "certificate_of_incorporation",
  "status": "pending",
  "createdAt": "2026-02-04T15:45:52.175Z",
  "updatedAt": "2026-02-04T16:30:00.000Z"
}

Response 404:

{
  "message": "Document of type 'certificate_of_incorporation' not found. Use POST to create a new document."
}

Document Types

Type
`certificate_of_incorporation`
`formation_document`
`power_of_attorney`
`corporate_structure`
`director_structure`
`proof_of_address`
`annual_financial_statements`
`articles_of_association`

Document Status

Status	Description
`pending`	Awaiting review
`approved`	Document verified
`rejected`	Document rejected

Shareholders

GET /v1/customers/business/:id/shareholders

Returns all shareholders for the business customer.

Response 200:

{
  "shareholders": [
    {
      "id": "sh_xxx",
      "firstName": "John",
      "lastName": "Smith",
      "birthDate": "1985-03-20",
      "email": "john@example.com",
      "ownershipPercentage": 60,
      "hasControl": true,
      "isSigner": true,
      "isDirector": true,
      "address": {
        "country": "US",
        "streetAddress": "456 Oak Avenue",
        "city": "San Francisco",
        "zip": "94102"
      },
      "attestedOwnershipStructureAt": null,
      "createdAt": "2026-02-04T15:45:52.175Z",
      "updatedAt": "2026-02-04T15:45:52.175Z"
    }
  ]
}

POST /v1/customers/business/:id/shareholders

Creates a new shareholder for the business customer.

Request:

{
  "firstName": "John",
  "lastName": "Smith",
  "birthDate": "1985-03-20",
  "email": "john@example.com",
  "ownershipPercentage": 60,
  "hasControl": true,
  "isSigner": true,
  "isDirector": true,
  "address": {
    "country": "US",
    "streetAddress": "456 Oak Avenue",
    "city": "San Francisco",
    "zip": "94102"
  }
}

Response 201:

{
  "id": "sh_xxx",
  "firstName": "John",
  "lastName": "Smith",
  "birthDate": "1985-03-20",
  "email": "john@example.com",
  "ownershipPercentage": 60,
  "hasControl": true,
  "isSigner": true,
  "isDirector": true,
  "address": {
    "country": "US",
    "streetAddress": "456 Oak Avenue",
    "city": "San Francisco",
    "zip": "94102"
  },
  "attestedOwnershipStructureAt": null,
  "createdAt": "2026-02-04T15:45:52.175Z",
  "updatedAt": "2026-02-04T15:45:52.175Z"
}

GET /v1/customers/business/:id/shareholders/:shareholderId

Returns a single shareholder by ID.

PUT /v1/customers/business/:id/shareholders/:shareholderId

Updates a shareholder. Only provided fields will be updated.

Request:

{
  "ownershipPercentage": 75,
  "title": "CEO"
}

DELETE /v1/customers/business/:id/shareholders/:shareholderId

Deletes a shareholder and their associated documents.

Response 200:

{
  "success": true,
  "message": "Shareholder deleted successfully"
}

Shareholder Fields

Field	Type	Required
`firstName`	`string`	Yes
`lastName`	`string`	Yes
`birthDate`	`string`	Yes
`email`	`string`	Yes
`ownershipPercentage`	`number`	Yes
`hasControl`	`boolean`	Yes
`isSigner`	`boolean`	Yes
`isDirector`	`boolean`	Yes
`address`	`object`	Yes
`phone`	`string`	No
`title`	`string`	No
`identityDocument`	`object`	No
`attestedOwnershipStructureAt`	`string`	No

Shareholder Documents

POST /v1/customers/business/:id/shareholders/:shareholderId/documents

Upload a document for a shareholder.

Request:

{
  "type": "passport_front",
  "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

Shareholder Document Types

Type	Description
`passport_front`	Passport front page
`passport_back`	Passport back page
`id_card_front`	ID card front
`id_card_back`	ID card back
`drivers_license_front`	Driver's license front
`drivers_license_back`	Driver's license back
`proof_of_address`	Proof of address

On this page