Skip to main content
POST
Submit a customer onboarding application

Authorizations

x-api-key
string
header
required

Headers

Idempotency-Key
string
required

Caller-generated unique key that lets the server safely replay this request. The original response is returned for 30 days on any retry with the same key from the same organization. Required on every state-changing money-moving or resource-creating POST.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_.:-]{1,128}$
Example:

"01J7B3K2X9M8N5P6Q7R8S9T0V1"

Body

application/json
businessInfo
object

Business-level data about the entity. Which leaves are required for a given country comes from GET /v2/onboarding/requirements.

registeredAddress
object

Registered business address. country accepts ISO 3166-1 alpha-2 or alpha-3. Which leaves are required for a given country comes from GET /v2/onboarding/requirements.

operatingAddress
object

Operating address when it differs from the registered one. Same leaves and country rules.

companyClassification
object

Legal-structure and industry classification. legalStructure and primaryIndustry are jurisdiction-specific; take their accepted values from GET /v2/onboarding/requirements.

businessActivity
object

Operating-activity descriptors. Which leaves are required for a given country comes from GET /v2/onboarding/requirements.

compliance
object

Compliance-programme attestations. Optional on customer onboarding: GET /v2/onboarding/requirements never lists these leaves, so send them only if they apply.

regulatoryHistory
object

Regulatory and adverse-action history. Which leaves are required for a given country comes from GET /v2/onboarding/requirements.

ownership
object

Beneficial-owner and controlling-person disclosure under persons[]. Persons are natural people: disclose a corporate owner under relatedCompany and look through it to the individuals behind it. How many persons each role needs, and which per-person leaves they owe, comes from individualRequirements[] in GET /v2/onboarding/requirements. Each person also carries roles[] and documentIds[].

Related-company disclosure for affiliated entities — a parent, subsidiary, sister company or holding entity. Optional on customer onboarding: GET /v2/onboarding/requirements never lists these leaves, so send them only if they apply. It does not replace ownership.persons[], which still needs the natural persons behind any corporate owner.

certification
object

Legal certifications the customer must affirm. A mustEqual: true marker in GET /v2/onboarding/requirements indicates an exact-value gate.

documentIds
string[]

Customer-level document IDs from POST /v2/documents to attach to this onboarding. Per-person documents go on ownership.persons[i].documentIds[].

Maximum array length: 100
Minimum string length: 1
Example:
clientReferenceId
string

Optional integrator-supplied identifier echoed back on the application record for cross-system correlation. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces.

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$
Example:

"ext_customer_8421"

Response

The submitted onboarding application

id
string
required

Unique application identifier

Pattern: ^app_[0-9A-Za-z]{22}$
status
enum<string>
required

Current lifecycle status of the application

Available options:
pending,
processing,
approved,
rejected,
cancelled
Example:

"pending"

createdAt
string<date-time>
required

Timestamp when the application was created

Example:

"2026-01-15T09:30:00.000Z"

updatedAt
string<date-time>
required

Timestamp when the application was last modified

Example:

"2026-01-15T09:30:00.000Z"

type
enum<string>
required
Available options:
customer_onboarding
clientReferenceId
string

Client-provided identifier for cross-referencing. Omitted when the client did not supply one. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces.

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$
Example:

"ext-12345"

submittedAt
string<date-time>

Timestamp when the application was submitted for review. Omitted while still in progress.

Example:

"2026-01-15T09:30:00.000Z"

failureCode
enum<string>

Machine-readable failure code on rejected applications. Omitted on non-rejected applications.

Available options:
rejected_by_ops,
compliance_denied
failureMessage
string

Customer-facing failure message accompanying failureCode. Omitted on non-rejected applications.

resubmittable
boolean

Whether a corrected application will be considered. true: correct the data and submit a fresh application. false: the decision is final, do not resubmit. Omitted on non-rejected applications.

customerId
string

Customer this onboarding application produced. Omitted while the application is still being reviewed; present after approval persists the customer row.

Pattern: ^cus_[0-9A-Za-z]{22}$
persons
object[]

People declared on the submission (beneficial owners and controlling persons), in submit order. Omitted before the application carries a submission.