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"
}
'const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
type: 'kyb_approve',
applicant_id: '01HABCDEFG1234567890XYZ',
simulation_id: 'sim_kyb_approve_001'
})
};
fetch('https://api.platform.dakota.xyz/sandbox/simulate/onboarding', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.platform.dakota.xyz/sandbox/simulate/onboarding"
payload = {
"type": "kyb_approve",
"applicant_id": "01HABCDEFG1234567890XYZ",
"simulation_id": "sim_kyb_approve_001"
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.platform.dakota.xyz/sandbox/simulate/onboarding"
payload := strings.NewReader("{\n \"type\": \"kyb_approve\",\n \"applicant_id\": \"01HABCDEFG1234567890XYZ\",\n \"simulation_id\": \"sim_kyb_approve_001\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"simulation_id": "sim_kyb_approve_001",
"applicant_id": "01HABCDEFG1234567890XYZ",
"previous_state": "pending",
"new_state": "approved"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "Invalid request",
"instance": "https://api.platform.dakota.xyz/sandbox/simulate/onboarding",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#forbidden",
"title": "Not available in production",
"status": 403,
"detail": "Not available in production",
"instance": "https://api.platform.dakota.xyz/sandbox/simulate/onboarding",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Applicant not found",
"status": 404,
"detail": "Applicant not found",
"instance": "https://api.platform.dakota.xyz/sandbox/simulate/onboarding",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#internal-error",
"title": "Failed to apply transition",
"status": 500,
"detail": "Failed to apply transition",
"instance": "https://api.platform.dakota.xyz/sandbox/simulate/onboarding",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}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.
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"
}
'const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
type: 'kyb_approve',
applicant_id: '01HABCDEFG1234567890XYZ',
simulation_id: 'sim_kyb_approve_001'
})
};
fetch('https://api.platform.dakota.xyz/sandbox/simulate/onboarding', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.platform.dakota.xyz/sandbox/simulate/onboarding"
payload = {
"type": "kyb_approve",
"applicant_id": "01HABCDEFG1234567890XYZ",
"simulation_id": "sim_kyb_approve_001"
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.platform.dakota.xyz/sandbox/simulate/onboarding"
payload := strings.NewReader("{\n \"type\": \"kyb_approve\",\n \"applicant_id\": \"01HABCDEFG1234567890XYZ\",\n \"simulation_id\": \"sim_kyb_approve_001\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"simulation_id": "sim_kyb_approve_001",
"applicant_id": "01HABCDEFG1234567890XYZ",
"previous_state": "pending",
"new_state": "approved"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "Invalid request",
"instance": "https://api.platform.dakota.xyz/sandbox/simulate/onboarding",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#forbidden",
"title": "Not available in production",
"status": 403,
"detail": "Not available in production",
"instance": "https://api.platform.dakota.xyz/sandbox/simulate/onboarding",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#not-found",
"title": "Applicant not found",
"status": 404,
"detail": "Applicant not found",
"instance": "https://api.platform.dakota.xyz/sandbox/simulate/onboarding",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}{
"type": "https://docs.dakota.xyz/api-reference/errors#internal-error",
"title": "Failed to apply transition",
"status": 500,
"detail": "Failed to apply transition",
"instance": "https://api.platform.dakota.xyz/sandbox/simulate/onboarding",
"request_id": "req_01hzy6y7v8w9x0y1z2a3b4c5d6"
}Authorizations
Headers
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.
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.
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 "insufficient_funds"
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.
transaction_processing, compliance_check, account_validation, provider_call, kyb_submission, kyb_approval, network_call 100"provider_call"
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.
100 <= x <= 599503
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.
500"Provider temporarily unavailable for maintenance."
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.
true
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.
true
Body
The onboarding transition to simulate
kyb_approve, kyb_reject, kyb_info_request, kyc_approve, kyc_reject, kyc_info_request, applicant_activate, applicant_suspend The onboarding application ID (from POST /applications)
"01H..."
Unique ID for this simulation (for idempotency and tracing)
1 - 128"sim_03H..."
Organization ID (for context; optional, used for logging)
"org_01H..."
Optional reason code for reject/info_request transitions
"MISSING_EIN"
Fields to request (for *_info_request types only)
["ssn", "address"]
Was this page helpful?

