Create onboarding.
Orchestrated onboarding that creates an entity, attaches documents and relationships, creates a customer, and optionally submits for KYB review — all in one call. This is a convenience wrapper over the granular entity/customer endpoints.
What this endpoint does (in order):
- Creates an Entity with the provided identity fields
- Attaches any pre-uploaded documents via
documentIds - Creates entity relationships (for business entities)
- Creates a Customer linked to the new entity
- If
autoSubmit: true, submits the customer for KYB review
Prerequisites: For business onboardings with relationships, the related individual entities must already exist (create them first via POST /entities). Pre-uploaded documents can be referenced by ID.
Next steps: Monitor the onboarding.completed webhook or poll GET /onboardings/{id} to check status. Once completed, create accounts and begin transacting.
Authorizations
API key issued at onboarding. Passed as a Bearer token in the Authorization header: Authorization: Bearer <api-key>. Identifies the caller and determines organization scope. Invalid or revoked keys return 401 with error type authentication_error.
Ed25519 or RSA-SHA256 asymmetric signature over the request payload (ADR-0015). Provides request integrity and non-repudiation. The signature covers the HTTP method, path, query string, request body, and timestamp. Invalid signatures return 401 with error type authentication_error.
Unix timestamp (seconds) of when the request was signed. Server rejects requests where the timestamp drifts beyond +/-60 seconds from server time to prevent replay attacks. Must match the timestamp used in the signature computation.
Headers
Idempotency key for this request. UUID v4 recommended. Max 128 characters. 24-hour retention. Same key + same body replays original response with Idempotency-Replayed: true. Same key + different body returns 409 (code: duplicate_idempotency_key). Same key while the original request is still processing returns 409 with a Retry-After header (code: idempotency_key_in_flight).
128"550e8400-e29b-41d4-a716-446655440000"
Body
Orchestrated onboarding request. Combines entity creation, document attachment, relationship linking, and customer enrollment into a single call. Provide individual-specific or business-specific fields based on entityType.
The type of legal entity.
individual, business Full legal name (required when entityType is individual).
Date of birth (required when entityType is individual).
^[0-9]{4}-[0-9]{2}-[0-9]{2}$"1985-03-15"
Nationality (required when entityType is individual).
^[A-Z]{2}$"US"
Government-issued ID (when entityType is individual).
Legal business name (required when entityType is business).
Trading or DBA name (when entityType is business).
Business registration number (when entityType is business).
Country of incorporation (when entityType is business).
^[A-Z]{2}$"US"
Date of incorporation (when entityType is business).
^[0-9]{4}-[0-9]{2}-[0-9]{2}$"1985-03-15"
Legal structure (when entityType is business).
corporation, llc, llp, partnership, sole_proprietorship, trust, non_profit, government_entity Industry classification (when entityType is business).
money_services, banking, fintech, crypto_exchange, payments, remittance, insurance, lending, real_estate, import_export, professional_services, technology, gambling, precious_metals, consulting, legal_services, ecommerce, manufacturing, other Email address per RFC 5322.
"user@example.com"
Phone number in E.164 format.
^\+[1-9]\d{1,14}$"+14155551234"
Physical or mailing address. Used on Entity and Counterparty.
Entity relationships to create (beneficial owners, directors, etc.). Each references an existing individual entity.
Pre-uploaded document IDs to attach to the entity.
Document resource identifier.
^doc_[A-Za-z0-9]+$If true, automatically submits the customer for KYB review after creation.
Consumer-defined key-value store. Available on all primary resources. Max 50 keys. Keys must match ^[a-zA-Z0-9_]{1,40}$. Values are strings (max 500 chars) or null.
Response
Onboarding created.
Orchestrated onboarding result. Wraps the entity, customer, and relationship creation into a single trackable resource. The onboarding progresses through pending → processing → completed (or failed).
Onboarding resource identifier.
^onb_[A-Za-z0-9]+$"onb_01953e1a5f4b7800"
Status of an orchestrated onboarding request.
pending, processing, completed, failed Entity resource identifier.
^ent_[A-Za-z0-9]+$"ent_01953e1a5f4b7100"
Customer resource identifier.
^cus_[A-Za-z0-9]+$"cus_01953e1a5f4b7000"
UTC timestamp in RFC 3339 / ISO 8601 format.
"2026-02-23T12:00:00Z"
IDs of entity relationships created during onboarding (beneficial owners, directors, etc.).
Entity relationship resource identifier.
^erel_[A-Za-z0-9]+$Know Your Business verification status.
not_started, pending, approved, rejected, requires_info UTC timestamp in RFC 3339 / ISO 8601 format.
"2026-02-23T12:00:00Z"