Simulate an onboarding state transition

curl --request POST \
  --url https://api.platform.dakota.xyz/sandbox/simulate/onboarding \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "type": "kyb_approve",
  "applicant_id": "01HABCDEFG1234567890XYZ",
  "simulation_id": "sim_kyb_approve_001"
}
'

{
  "simulation_id": "sim_kyb_approve_001",
  "applicant_id": "01HABCDEFG1234567890XYZ",
  "previous_state": "pending",
  "new_state": "approved"
}

Sandbox

Simulate an onboarding state transition

Drives KYB, KYC, or applicant account status through a sandbox transition without waiting for real compliance review. Available in sandbox mode only.

Type → effect mapping:

type	KYB status set	Application status set	webhooks emitted
`kyb_approve`	approved (via provisioning)	approved	2× `customer.kyb_status.created` (one per provider, `kyb_status: approved`) + `recipient.created`
`kyb_reject`	—	declined	(none — application status only)
`kyb_info_request`	—	request_for_information	(none — application status only)
`kyc_approve`	—	approved	(none — application status only)
`kyc_reject`	—	declined	(none — application status only)
`kyc_info_request`	—	request_for_information	(none — application status only)
`applicant_activate`	approved (via provisioning)	approved	2× `customer.kyb_status.created` (one per provider, `kyb_status: approved`) + `recipient.created`
`applicant_suspend`	—	declined	(none — application status only)

Approving customers (individual or business): Use kyb_approve to fully approve any customer type. This triggers the complete onboarding flow including endorsement and recipient creation. The kyc_* types only update the individual applicant’s KYC application status without triggering the full onboarding flow.

Note: applicant_activate does NOT auto-create payment accounts, wallets, or account numbers. Create those separately via the account creation API after activation.

POST

sandbox

simulate

onboarding

Simulate an onboarding state transition

curl --request POST \
  --url https://api.platform.dakota.xyz/sandbox/simulate/onboarding \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "type": "kyb_approve",
  "applicant_id": "01HABCDEFG1234567890XYZ",
  "simulation_id": "sim_kyb_approve_001"
}
'

{
  "simulation_id": "sim_kyb_approve_001",
  "applicant_id": "01HABCDEFG1234567890XYZ",
  "previous_state": "pending",
  "new_state": "approved"
}

Authorizations

x-api-key

string

header

required

Headers

x-idempotency-key

string<uuid>

required

Unique key to ensure request idempotency. If the same key is used within a certain time window, the original response will be returned instead of executing the request again.

X-Sandbox-Scenario

enum<string>

Sandbox-only. Applies a preset failure or behavior mode for the request, selecting a coherent combination of error step, status, and message. The full set of scenarios is also exposed dynamically via GET /sandbox/scenarios along with descriptions and per-rail applicability. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Available options:

happy_path,

delayed_settlement,

insufficient_funds,

compliance_block,

invalid_account,

provider_maintenance,

network_congestion,

kyb_manual_review,

kyb_rejected,

kyb_expired,

network_timeout,

intermittent_errors,

account_frozen,

document_expired,

invalid_swift

Example:

"insufficient_funds"

X-Sandbox-Error-Step

enum<string>

Sandbox-only. Names the pipeline step at which the injected error fires. Pair with X-Sandbox-Error-Status and (optionally) X-Sandbox-Error-Message to drive a deterministic failure mode at a known point in the request lifecycle. Values longer than 100 characters are ignored. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Available options:

transaction_processing,

compliance_check,

account_validation,

provider_call,

kyb_submission,

kyb_approval,

network_call

Maximum string length: 100

Example:

"provider_call"

X-Sandbox-Error-Status

integer

Sandbox-only. Sets the HTTP status code returned when the sandbox injects an error at the configured step (see X-Sandbox-Error-Step). Must be a valid HTTP status code in the range 100-599; values outside that range are ignored. Status codes >= 400 cause the request to short-circuit immediately with a structured error response. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Required range: 100 <= x <= 599

Example:

503

X-Sandbox-Error-Message

string

Sandbox-only. Sets the human-readable message field of the injected sandbox error response. Truncated values longer than 500 characters are ignored. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Maximum string length: 500

Example:

"Provider temporarily unavailable for maintenance."

X-Sandbox-Instant-Completion

boolean

default:false

Sandbox-only. When true, asynchronous simulation flows complete immediately rather than progressing through their normal timed states. Useful for fast end-to-end test runs that do not need to exercise intermediate webhook events. Accepts true/false (also 1/0, yes/no); other values are treated as false. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Example:

true

X-Sandbox-Skip-Auto-Approval

boolean

default:false

Sandbox-only. When true, prevents the default 5-second KYB auto-approval that the sandbox applies to newly created customers. Use this header (typically with X-Sandbox-Scenario: kyb_manual_review or kyb_rejected) to keep an application in pending so integrators can exercise manual-review and rejection flows. Accepts true/false (also 1/0, yes/no); other values are treated as false. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Example:

true

Body

application/json

type

enum<string>

required

The onboarding transition to simulate

Available options:

kyb_approve,

kyb_reject,

kyb_info_request,

kyc_approve,

kyc_reject,

kyc_info_request,

applicant_activate,

applicant_suspend

applicant_id

string

required

The onboarding application ID (from POST /applications)

Example:

"01H..."

simulation_id

string

required

Unique ID for this simulation (for idempotency and tracing)

Required string length: 1 - 128

Example:

"sim_03H..."

organization_id

string

Organization ID (for context; optional, used for logging)

Example:

"org_01H..."

reason_code

string

Optional reason code for reject/info_request transitions

Example:

"MISSING_EIN"

info_request_fields

string[]

Fields to request (for *_info_request types only)

Example:

["ssn", "address"]

Response

Onboarding transition applied

simulation_id

string

applicant_id

string

previous_state

string

KYB status before the transition

new_state

string

KYB status after the transition

Simulate an inbound payment event Get simulation status

⌘I