In the MVP API, orchestrated onboarding is the supported path for creating entities and customers. The onboarding endpoint creates both resources in a single call and optionally submits the customer for KYB review with autoSubmit: true.
KYB model: KYB in the initial release is manual. OpenFX submits business onboarding data via POST /onboardings. The banking infrastructure provider makes the approval decision. There is no automated KYB decisioning — approval is an asynchronous, human-reviewed process.

​
What is orchestrated onboarding?

The orchestrated onboarding endpoint (POST /onboardings) wraps entity creation and customer enrollment into a single API call. One request:
  1. Creates an entity (individual or business)
  2. Creates a customer linked to the new entity
  3. Optionally submits the customer for KYB review
The result is a trackable Onboarding resource that you can poll or monitor via webhooks.

​
Onboarding lifecycle

StatusDescription
pendingOnboarding request received, not yet processing.
processingEntity and customer creation in progress.
completedAll resources created successfully. If autoSubmit was true, customer has been submitted for KYB review.
failedOne or more steps could not be completed. Check the onboarding for details.

​
Creating an orchestrated onboarding

​
Onboard an individual

curl -X POST "https://sandbox.api.openfx.com/v1/onboardings" \
  -H "Authorization: Bearer ofx_sk_sandbox_abc123def456" \
  -H "X-Signature: <your-ed25519-signature>" \
  -H "X-Timestamp: 1740500000" \
  -H "Idempotency-Key: ff0e8400-e29b-41d4-a716-446655440080" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "individual",
    "fullName": "Jane Doe",
    "dateOfBirth": "1985-03-15",
    "nationality": "US",
    "email": "jane@example.com",
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    },
    "autoSubmit": true
  }'

​
Onboard a business

curl -X POST "https://sandbox.api.openfx.com/v1/onboardings" \
  -H "Authorization: Bearer ofx_sk_sandbox_abc123def456" \
  -H "X-Signature: <your-ed25519-signature>" \
  -H "X-Timestamp: 1740500000" \
  -H "Idempotency-Key: 110e8400-e29b-41d4-a716-446655440090" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "business",
    "legalName": "Acme Payments Inc.",
    "tradingName": "Acme Pay",
    "registrationNumber": "12345678",
    "jurisdiction": "US",
    "incorporationDate": "2020-06-15",
    "businessStructure": "corporation",
    "industryCode": "payments",
    "email": "compliance@acme.com",
    "address": {
      "line1": "456 Market St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "autoSubmit": true
  }'
The response: 
{
  "id": "onb_01953e1a5f4b7800",
  "status": "completed",
  "entityId": "ent_01953e1a5f4b7200",
  "customerId": "cus_01953e1a5f4b7000",
  "kybStatus": "pending",
  "createdAt": "2026-02-23T12:00:00Z",
  "updatedAt": "2026-02-23T12:00:01Z"
}

​
Key request fields

FieldTypeRequiredDescription
entityTypestringYes"individual" or "business"
fullNamestringConditionalRequired when entityType is individual
legalNamestringConditionalRequired when entityType is business
jurisdictionstringConditionalRequired when entityType is business
autoSubmitbooleanNoIf true, automatically submits the customer for KYB review. Defaults to false.
metadataobjectNoCustom key-value pairs passed to the customer resource.

​
Progressive onboarding

“Progressive onboarding” means upgrading from an existing trade-platform KYB to banking KYB — not partial banking access. A customer who has already been KYB’d on the trade platform can upgrade to banking with incremental document collection, rather than starting from scratch.
Under the hood, POST /onboardings orchestrates a multi-step flow with the banking provider: it creates a business applicant record (POST /business_applicants on the provider side), then creates an onboarding tied to that applicant. OpenFX derives kybStatus from the provider’s onboarding status. This orchestration is invisible to the API consumer.

​
Monitoring onboarding status

​
Webhook events

EventWhen it fires
onboarding.createdOnboarding request is received
onboarding.completedAll resources created successfully
onboarding.failedOne or more steps could not be completed
After receiving onboarding.completed, you still need to wait for the KYB decision if autoSubmit was true. Subscribe to customer.kyb_status_changed to know when the customer is approved and ready to transact.

​
Polling

If you prefer polling over webhooks, use GET /onboardings/{onboardingId} to check status: 
curl -X GET "https://sandbox.api.openfx.com/v1/onboardings/onb_01953e1a5f4b7800" \
  -H "Authorization: Bearer ofx_sk_sandbox_abc123def456" \
  -H "X-Signature: <your-ed25519-signature>" \
  -H "X-Timestamp: 1740500000"

​
Listing onboardings

# List all onboardings
curl -X GET "https://sandbox.api.openfx.com/v1/onboardings?limit=20" \
  -H "Authorization: Bearer ofx_sk_sandbox_abc123def456" \
  -H "X-Signature: <your-ed25519-signature>" \
  -H "X-Timestamp: 1740500000"

# Filter by status
curl -X GET "https://sandbox.api.openfx.com/v1/onboardings?status=completed" \
  -H "Authorization: Bearer ofx_sk_sandbox_abc123def456" \
  -H "X-Signature: <your-ed25519-signature>" \
  -H "X-Timestamp: 1740500000"
After the customer reaches active status, you can create accounts (POST /accounts), set up counterparties (POST /counterparties), and send payments (POST /payments). The full platform is unlocked.

​
Next steps

Customers & KYB

Deep dive into customer statuses, KYB tracking, progressive capabilities, and webhook handling.

Accounts & Balances

Open fiat and crypto accounts once your customer is active.

Webhooks

Set up webhook subscriptions to receive real-time notifications for onboarding and KYB events.

​
API reference