> ## Documentation Index > Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.yaml post /sandbox/simulate/onboarding openapi: 3.0.3 info: title: Dakota Platform API version: 1.0.0 description: >- Combined API specification for Dakota Platform services: - Issuance API: Asset minting and burning operations - Onboarding API: Know Your Business/Customer verification - On/Off Ramp API: Managing on-ramp and off-ramp accounts - Recipients API: Managing destinations for KYB'd entities - Transactions API: Viewing transaction history across platform operations ## Authentication and API Headers All API endpoints require the following headers: - `x-idempotency-key`: Required for all POST endpoints to ensure request idempotency - `x-api-key`: Required for authentication across all endpoints Note: On /applications endpoints you need a token for authentication instead of a x-api-key - `x-application-token`: Required for authentication on public /applications endpoints (alternative to `x-api-key` where documented) ## Rate Limits Requests are rate limited per API key. Every response includes the following headers: | Header | Description | | --- | --- | | `X-RateLimit-Limit` | Maximum requests allowed in the current one-minute window. | | `X-RateLimit-Remaining` | Requests remaining in the current window. | | `X-RateLimit-Reset` | Absolute Unix timestamp (seconds since epoch) when the current rate-limit window resets. | When a request is throttled (`429`), responses also include `Retry-After` with seconds to wait before retrying. servers: - url: https://api.platform.dakota.xyz description: Production environment - url: https://api.platform.sandbox.dakota.xyz description: Sandbox — safe for testing with simulated data security: - ApiKeyAuth: [] tags: - name: Agentic Payments x-alpha: true description: >- Alpha — agent-driven payments: provision agents, draft and approve spending mandates, accept reviewed instructions, and manage scheduled payments. **Prerequisites:** Customer onboarded; signer groups attached for recognition. **Related:** Wallets, Signer Groups, Transactions - name: Mandates x-alpha: true description: >- Alpha — spending mandates: signed, signer-bound authorizations governing what may be spent, approved or cancelled by a second recognized signer (§8 — the dual-control rule that every mandate mutation must be signed by a recognized signer OTHER than the bound one). Independent of agents and scheduled payments. **Prerequisites:** Signer groups attached for recognition. **Related:** Signer Groups, Transactions - name: Insights x-alpha: true description: >- Alpha — read-only account insight: a deterministic report over a customer's agentic activity (funding balances, upcoming obligations, failures, mandate headroom and expiry) plus an advisory chat that narrates it. Never moves money, never creates or changes anything. **Prerequisites:** Customer onboarded; insight is computed from the customer's scheduled payments, mandates, and wallets. **Related:** Agentic Payments, Mandates - name: Customers description: >- Manage customer entities representing businesses and organizations onboarded to Dakota. **Prerequisites:** Complete KYB via Onboarding endpoints before initiating money movement. **Related:** Onboarding, Recipients, Transactions, Accounts, Wallets - name: Wallets description: >- Manage wallets, balances, and wallet-to-signer-group relationships for custody and movement controls. **Prerequisites:** Customer must exist. Configure signer groups before policy-enforced workflows. **Related:** Signer Groups, Policies, Transactions, Customers - name: Transactions description: >- Create, cancel, and retrieve transaction records across account and wallet flows. **Prerequisites:** Accounts or destinations must be configured based on flow type. **Related:** Accounts, Recipients, Policies, Events - name: Recipients description: >- Manage recipient entities and destination rails used by customers for payouts and transfers. **Prerequisites:** Customer must be onboarded and active. **Related:** Customers, Transactions, Accounts, Onboarding - name: Accounts description: >- Manage account resources used for onramp, offramp, and swap operations. **Prerequisites:** Customer must be created and network/asset constraints must be known. **Related:** Customers, Transactions, Auto Transactions, Info - name: Auto Transactions description: >- Manage automated transaction configurations and execution history for account automation workflows. **Prerequisites:** Source account must exist and be configured for automation. **Related:** Accounts, Transactions, Events - name: Onboarding description: >- Manage KYB/KYC onboarding lifecycle, application documents, attestations, and verification steps. **Prerequisites:** Customer context and required entity/application metadata. **Related:** Customers, Exceptions, Recipients, Transactions - name: Policies description: >- Define and manage policy objects and rules used for transaction governance and risk controls. **Prerequisites:** Wallet and signer group resources should be configured for enforcement scenarios. **Related:** Wallets, Signer Groups, Transactions - name: Signer Groups description: >- Manage signer groups and signer assignments for multi-party authorization models. **Prerequisites:** Wallets should exist before linking signer groups. **Related:** Wallets, Policies, Transactions - name: Authentication description: >- Manage API authentication credentials and key lifecycle for platform access. **Prerequisites:** Client organization must be provisioned. **Related:** Users, Info - name: Users description: >- Manage client users, roles, and identity metadata for platform access control. **Prerequisites:** Auth credentials and client context must be established. **Related:** Authentication - name: Webhooks description: >- Manage outbound webhook targets and delivery configuration for event notifications. **Prerequisites:** Subscriber endpoint must be reachable and secured. **Related:** Events, Authentication - name: Payouts description: >- Manage where Dakota sends your accrued developer-fee payouts. **Prerequisites:** Auth credentials and client context must be established. **Related:** Events - name: Events description: >- Retrieve event records emitted by platform operations for audit and troubleshooting. **Prerequisites:** Requesting client must have access to referenced resources. **Related:** Webhooks, Transactions, Onboarding - name: Info description: >- Read platform capability metadata, such as supported rails, networks, and assets. **Prerequisites:** Valid authentication headers. **Related:** Accounts, Transactions - name: Sandbox description: >- Trigger sandbox-only simulation endpoints for safe end-to-end integration testing with synthetic data. The sandbox host (`https://api.platform.sandbox.dakota.xyz`) also accepts a family of `X-Sandbox-*` request headers on most write endpoints (`Customers`, `Accounts`, `Transactions`, simulate endpoints) that let integrators drive deterministic failure modes — pick a preset via `X-Sandbox-Scenario`, or compose a custom one with `X-Sandbox-Error-Step`/`X-Sandbox-Error-Status`/`X-Sandbox-Error-Message`. `X-Sandbox-Instant-Completion` collapses async flows to a single synchronous step, and `X-Sandbox-Skip-Auto-Approval` keeps newly created KYB applications in `pending` for manual-review testing. All `X-Sandbox-*` headers are ignored in production. **Prerequisites:** Sandbox environment and test customer data. **Related:** Customers, Accounts, Transactions, Onboarding paths: /sandbox/simulate/onboarding: post: tags: - Sandbox summary: Simulate an onboarding state transition description: > 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. operationId: simulateOnboarding parameters: - $ref: '#/components/parameters/IdempotencyKeyHeader' - $ref: '#/components/parameters/SandboxScenarioHeader' - $ref: '#/components/parameters/SandboxErrorStepHeader' - $ref: '#/components/parameters/SandboxErrorStatusHeader' - $ref: '#/components/parameters/SandboxErrorMessageHeader' - $ref: '#/components/parameters/SandboxInstantCompletionHeader' - $ref: '#/components/parameters/SandboxSkipAutoApprovalHeader' requestBody: required: true content: application/json: schema: type: object required: - type - applicant_id - simulation_id properties: type: type: string enum: - kyb_approve - kyb_reject - kyb_info_request - kyc_approve - kyc_reject - kyc_info_request - applicant_activate - applicant_suspend description: The onboarding transition to simulate applicant_id: type: string description: The onboarding application ID (from POST /applications) example: 01H... organization_id: type: string description: Organization ID (for context; optional, used for logging) example: org_01H... simulation_id: type: string minLength: 1 maxLength: 128 description: Unique ID for this simulation (for idempotency and tracing) example: sim_03H... reason_code: type: string description: Optional reason code for reject/info_request transitions example: MISSING_EIN info_request_fields: type: array items: type: string description: Fields to request (for *_info_request types only) example: - ssn - address example: type: kyb_approve applicant_id: 01HABCDEFG1234567890XYZ simulation_id: sim_kyb_approve_001 responses: '200': description: Onboarding transition applied content: application/json: schema: type: object properties: simulation_id: type: string applicant_id: type: string previous_state: type: string description: KYB status before the transition new_state: type: string description: KYB status after the transition example: simulation_id: sim_kyb_approve_001 applicant_id: 01HABCDEFG1234567890XYZ previous_state: pending new_state: approved '400': description: Invalid request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: 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 '403': description: Not available in production content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: 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 '404': description: Applicant not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: 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 '500': description: Failed to apply transition content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: 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 security: - ApiKeyAuth: [] externalDocs: description: Read full guide in docs url: https://docs.dakota.xyz/api-reference/sandbox/simulate-onboarding components: parameters: IdempotencyKeyHeader: name: x-idempotency-key in: header required: true description: >- 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. schema: type: string format: uuid SandboxScenarioHeader: name: X-Sandbox-Scenario in: header required: false description: >- 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. schema: type: string enum: - 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 SandboxErrorStepHeader: name: X-Sandbox-Error-Step in: header required: false description: >- 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. schema: type: string maxLength: 100 enum: - transaction_processing - compliance_check - account_validation - provider_call - kyb_submission - kyb_approval - network_call example: provider_call SandboxErrorStatusHeader: name: X-Sandbox-Error-Status in: header required: false description: >- 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. schema: type: integer minimum: 100 maximum: 599 example: 503 SandboxErrorMessageHeader: name: X-Sandbox-Error-Message in: header required: false description: >- 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. schema: type: string maxLength: 500 example: Provider temporarily unavailable for maintenance. SandboxInstantCompletionHeader: name: X-Sandbox-Instant-Completion in: header required: false description: >- 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. schema: type: boolean default: false example: true SandboxSkipAutoApprovalHeader: name: X-Sandbox-Skip-Auto-Approval in: header required: false description: >- 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. schema: type: boolean default: false example: true schemas: ProblemDetails: type: object required: - type - title - status description: | Error response following RFC 9457 Problem Details. Public API error responses use this format. example: type: https://docs.dakota.xyz/api-reference/errors#not-found title: Customer Not Found status: 404 detail: Customer cst_2abc123 was not found in your organization. instance: https://api.platform.dakota.xyz/customers/cst_2abc123 request_id: req_7f3a8b2c properties: type: type: string format: uri description: | URI reference identifying the problem type. Resolves to human-readable documentation. example: https://docs.dakota.xyz/api-reference/errors#not-found title: type: string description: >- Short, human-readable summary of the problem type. Stable across occurrences. example: Customer Not Found status: type: integer description: HTTP status code for this occurrence. example: 404 detail: type: string description: Human-readable explanation specific to this occurrence. example: Customer cst_2abc123 was not found in your organization. instance: type: string format: uri description: The request path that triggered this error. example: https://api.platform.dakota.xyz/customers/cst_2abc123 request_id: type: string description: Unique request identifier. Include when contacting support. example: req_7f3a8b2c errors: type: array description: Field-level validation errors (present for validation failures). items: $ref: '#/components/schemas/ValidationError' ValidationError: type: object required: - field - message properties: field: type: string description: Field path using dot notation for nested fields. example: bank_account.routing_number message: type: string description: Human-readable description of the field error. example: Routing number must be exactly 9 digits code: type: string description: Machine-readable error code for this field. example: invalid_format securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````