> ## 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. # Update associated individual > Updates an associated individual's information for a business application (UBO, control person, or applicant). Applicants may call this in 'pending', 'request_for_information' or 'compliance_review'; Dakota admins may additionally call it in 'admin_revision'. ## OpenAPI ````yaml /openapi.yaml put /applications/{application_id}/associated-individuals/{individual_id} 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-beta: true description: >- Beta — 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-beta: true description: >- Beta — 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-beta: true description: >- Beta — read-only insight: a deterministic report over a customer's agentic activity (funding balances, upcoming obligations, failures, mandate headroom and expiry), or — via `GET /insights` — over the whole client's book, with portfolio KPIs, daily series and a per-customer roll-up. 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: Cards description: >- Issue and manage cardholders and cards, and follow card transactions. Every change is also delivered as a webhook event. **Prerequisites:** Customer must be onboarded and the cards capability must be available. **Related:** Customers, Wallets, Events ### Webhook event catalog (v1) Every card-family event a client can subscribe to, in one place: | Event | Fires when | | -- | -- | | `cardholder.created` | A cardholder is created. | | `cardholder.updated` | Any cardholder change, including every review-status transition and deletion (`status: closed`). | | `cardholder.information_requested` | A reviewer asks for more information; the payload lists the open requirements. Not yet emitted; the review pipeline that opens a request for information is still to land. | | `card.created` | A card is created. | | `card.updated` | Any card change: status, spend limit, last4, freeze sources. A close arrives here with `status: closed`. | | `card_transaction.created` | The first event for a transaction, normally an authorization (`status: authorized`) placing a hold. A declined authorization also arrives here, with `status: declined`. | | `card_transaction.updated` | Every later change to the same transaction (see below). | | `wallet.card_enablement.completed` | A wallet's card-settlement enablement became active. | **Card event ordering.** `card.created` and `card.updated` carry the card as it stands after the change, including `version` and `freeze_sources` (always an array, empty when nothing holds the card). `version` is strictly increasing per card and matches the `version` on the card resource. Deliveries can arrive out of order, so keep the highest `version` you have applied for each card and drop any event whose `version` is not greater than it. **One transaction stream.** Holds, releases, partial clearings, settlement, returns, disputes and force posts are not separate event types. They are `status` transitions on the transaction, delivered as `card_transaction.updated` with the same payload shape as `card_transaction.created`: | What happened | `status` on the event | | -- | -- | | Transaction known before its first authorization event | `pending` (on `card_transaction.created`) | | Hold placed (authorization) | `authorized` (on `card_transaction.created`, or `card_transaction.updated` after a `pending` start) | | Hold released without clearing (merchant, issuer or network reversal) | `auth_reversed` | | Hold expired unused | `expired` | | Part of the hold settled | `partially_cleared` (with the new `cleared_amount`) | | Fully settled | `cleared` | | Settled with no prior hold | `force_posted` | | Merchant refund | `returned`, on a new card transaction for the refund; the original purchase stays `cleared`. The network returned the money; read `refund_state` for whether it reached the customer's wallet (`pending` then `paid`). `returned` alone is not proof of payout. | | Chargeback opened | `disputed` (reserved; not emitted yet) | | Authorization refused | `declined` (on `card_transaction.created`, or `card_transaction.updated` when the transaction already exists). Moves no money; read `decline_reason` and `decline_code` for why. | `outstanding_amount` is the part of `cleared_amount` that no authorization covered, less any refunds: non-zero after a force post or an over-capture. **Naming.** A dotted segment names a sub-resource of the resource before it, so `wallet.card_enablement.*` is a wallet's card enablement. `card_transaction.*` carries an underscore because the resource is `card_transactions`, a top-level resource, not a sub-resource of a card. It is not a typo, and there is no `card.transaction.*` family, and no separate settlement event: settlement is a `status` on `card_transaction.updated`. - 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: RD Marketing Fee description: >- Everything behind your RD marketing fee: read what a month came to, declare the wallets you hold outside Dakota so the RD in them counts, and say where the fee should be sent. **Prerequisites:** Client must be in the RD marketing-fee programme. A month is readable once it has closed. **Related:** Wallets, Events - name: Self Serve description: >- Buy and track prepaid credits, and read the tiers and pricing they are sold at. **Prerequisites:** Auth credentials and client context must be established. **Related:** Billing - 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. These operations are served under `/capabilities/*` - `GET /capabilities/countries` and `GET /capabilities/networks`. The tag name does not appear in the request paths. **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 - name: Legal description: |- The legal documents customers accept — terms of service, privacy policy, e-sign notice, and partner agreements. Dakota publishes these here, and this is the authoritative source: the hosted onboarding flow, the dakota.xyz website, and your own integration all read the same revisions. Present the current revision to your customer before capturing their acceptance so the record reflects the text they actually saw. paths: /applications/{application_id}/associated-individuals/{individual_id}: put: tags: - Onboarding summary: Update associated individual description: > Updates an associated individual's information for a business application (UBO, control person, or applicant). Applicants may call this in 'pending', 'request_for_information' or 'compliance_review'; Dakota admins may additionally call it in 'admin_revision'. operationId: updateAssociatedIndividual parameters: - $ref: '#/components/parameters/IdempotencyKeyHeader' - name: application_id in: path required: true schema: $ref: '#/components/schemas/KSUID' - name: individual_id in: path required: true schema: $ref: '#/components/schemas/KSUID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IndividualRequest' example: roles: - ubo - control_person name: first: John middle: Michael last: Doe title: ceo ownership_percentage: 25.5 date_of_birth: '1985-06-15' ssn: 123-45-6789 nationalities: - US address: street1: 123 Main St street2: Apt 4B street3: Building C city: San Francisco region: CA postal_code: '94105' country: US email_address: john.doe@acme.com responses: '200': description: Associated individual updated successfully content: application/json: schema: $ref: '#/components/schemas/AssociatedIndividualResponse' example: application_id: 1NFHrqBHb3cTfLVkFSGmHZqdDPi application_status: pending application_decision: approved individual: id: 2hCjxJzUAW6JVRkZqaF9E0KpM3b first_name: John last_name: Doe date_of_birth: '1985-06-15' nationalities: - US address: street1: 123 Main St street2: Apt 4B street3: Building C city: San Francisco region: CA postal_code: '94105' country: US email_address: john.doe@acme.com phone_number: +1-555-123-4567 decision: approved decision_reason: All verification checks passed decision_by: admin@dakota.xyz decision_at: 1705315800 sumsub_verification: applicant_id: 2hCjxJzUAW6JVRkZqaF9E0KpM3b provider_applicant_id: 65a1b2c3d4e5f6g7h8i9j0k1 entity_type: individual type: individual decision: approved decision_reason: All verification checks passed decision_by: admin@dakota.xyz decision_at: 1705315800 review: review_id: 65a1b2c3d4e5f6g7h8i9j0k1 attempt_id: 65a1b2c3d4e5f6g7h8i9j0k2 attempt_cnt: 1 level_name: basic-kyc-level create_date: '2024-01-15T10:30:00Z' review_date: '2024-01-15T14:45:00Z' review_status: completed review_result: review_answer: GREEN reject_labels: - DOCUMENT_TEMPLATE - FRAUDULENT_PATTERNS reject_type: FINAL button_ids: - approve moderation_comment: All documents verified successfully client_comment: Approved for onboarding risk_labels: device: - EMULATOR - VPN cross_check: - FAKE_ID - BLACKLIST attempt_id: 65a1b2c3d4e5f6g7h8i9j0k2 created_at: '2024-01-15T10:30:00Z' roles: - ubo - control_person ownership_percentage: 25.5 title: CEO '400': description: Invalid request or validation errors content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.dakota.xyz/api-reference/errors#invalid-request title: Invalid request or validation errors status: 400 detail: Invalid request or validation errors instance: >- https://api.platform.dakota.xyz/applications/example-id/associated-individuals/example-id request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6 '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: >- https://docs.dakota.xyz/api-reference/errors#authentication-error title: Unauthorized status: 401 detail: Unauthorized instance: >- https://api.platform.dakota.xyz/applications/example-id/associated-individuals/example-id request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6 '403': description: Application not in pending state or forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.dakota.xyz/api-reference/errors#forbidden title: Application not in pending state or forbidden status: 403 detail: Application not in pending state or forbidden instance: >- https://api.platform.dakota.xyz/applications/example-id/associated-individuals/example-id request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6 '404': description: Application or individual not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.dakota.xyz/api-reference/errors#not-found title: Application or individual not found status: 404 detail: Application or individual not found instance: >- https://api.platform.dakota.xyz/applications/example-id/associated-individuals/example-id request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6 '422': description: >- Unprocessable — the `X-Idempotency-Key` was already used on this endpoint with a different request body (problem type `idempotency-key-reused`). The request was not executed and the original response was not replayed. Resend the original body to receive the original response, or use a new key to make a new request. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' security: - ApplicationTokenAuth: [] externalDocs: description: Read full guide in docs url: >- https://docs.dakota.xyz/api-reference/onboarding/update-associated-individual components: parameters: IdempotencyKeyHeader: name: x-idempotency-key in: header required: true description: >- Unique key (UUID) to ensure request idempotency on POST, PUT and PATCH requests. A key is scoped to your client, the HTTP method and the path, and is remembered for 24 hours after a successful (below 400) response. Repeating the same request (same JSON body, whatever the key order or whitespace) with the same key within that window returns the original response with `X-Idempotent-Replayed: true` instead of executing the request again. Using the same key on the same endpoint with a different body returns `422` with problem type `idempotency-key-reused`; the request is not executed. Error responses (4xx and 5xx) are not remembered, so a request refused for a fixable reason can be corrected and retried under the same key. Request bodies that are not JSON (for example file uploads) are not compared. schema: type: string format: uuid schemas: KSUID: type: string title: KSUID description: >- KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform. pattern: ^[0-9A-Za-z]{27}$ minLength: 27 maxLength: 27 example: 1NFHrqBHb3cTfLVkFSGmHZqdDPi IndividualRequest: type: object description: > An individual person (used for both business associated persons and standalone individual applications). Several fields are required for one role and refused for another, so they cannot be listed in `required`. `employment_status` is required when `roles` is `[individual]` and rejected with 400 for any other role; `purpose_of_account` and `source_of_wealth` are needed for `[individual]` before the application can be submitted. `title` is required for `ubo` and `control_person` and rejected for `individual`. See `PUT /applications/{application_id}/individual-details` for the full table. required: - roles - name - date_of_birth - nationalities - address - email_address properties: roles: type: array description: >- Role(s) of this person (individual cannot be combined with other types) minItems: 1 items: type: string enum: - ubo - control_person - applicant - individual example: - ubo - control_person name: $ref: '#/components/schemas/PersonName' title: type: string description: >- Job title (required for UBO/control person, optional for applicant, invalid for individual) enum: - ceo - coo - cfo - cto - cco - director - other_officer example: ceo employment_status: type: string description: > Employment status. Required when `roles` is `[individual]`. Must be omitted for every other role (`ubo`, `control_person`, `applicant`): a request that sends it for those roles is rejected with 400. enum: - employed - self_employed - unemployed - student - retired example: employed ownership_percentage: type: number format: double description: >- Ownership percentage (required for UBO role, optional for others, must be > 0 and <= 100) minimum: 0.01 maximum: 100 example: 25.5 date_of_birth: type: string format: date description: >- Date of birth (ISO 8601 format, person must be at least 18 years old) example: '1985-06-15' ssn: type: string description: >- Social Security Number (required for US persons, format: XXX-XX-XXXX). On an update, leave it out to keep the SSN already on file, for example one imported from a share token. pattern: ^\d{3}-\d{2}-\d{4}$ example: 123-45-6789 nationalities: type: array description: ISO 3166-1 alpha-2 country codes for nationalities minItems: 1 items: type: string minLength: 2 maxLength: 2 example: - US address: $ref: '#/components/schemas/Address' email_address: type: string format: email description: Email address (cannot use example or test domains) example: john.doe@acme.com purpose_of_account: type: array description: >- Intended purposes for the account (required when roles includes 'individual') minItems: 1 items: type: string enum: - investing - sending_and_receiving_payments - storage_of_funds_or_digital_assets - making_online_payments - trading_on_other_platforms example: - investing - storage_of_funds_or_digital_assets source_of_wealth: type: array description: Sources of wealth (required when roles includes 'individual') minItems: 1 items: type: string enum: - investments - employment - court_settlement - lottery_winnings - retirement_income - savings - sale_of_assets - family_funds - gambling_winnings - gift - inheritance - insurance_claim - loan - redundancy_severance - benefits example: - employment - savings AssociatedIndividualResponse: type: object description: >- Response containing associated individual entity data with application context required: - application_id - application_status - application_decision - individual properties: application_id: $ref: '#/components/schemas/KSUID' description: The application ID application_status: $ref: '#/components/schemas/ApplicationStatus' description: Current status of the application application_decision: type: string enum: - approved - declined - withdrawn nullable: true description: Decision outcome (if any) individual: $ref: '#/components/schemas/AssociatedIndividualEntity' description: The associated individual entity data 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' resolution_url: type: string format: uri description: | A link the customer can follow to CLEAR this error, present only on problems with a concrete self-service remedy. Today this is returned by `#terms-not-accepted`, where it points at the hosted flow in which the outstanding agreement can be signed. The link is token-gated and usable as-is — send the customer to it directly rather than parsing it out of `detail`. example: >- https://onboarding.dakota.xyz/applications/2abc123?token=tok_7f3a8b2c user_message: type: string description: | A plain-language rendition of `detail` written for the end customer, present when one exists for this error. `detail` names request fields and actions so a machine caller (such as a payment agent drafting proposals) can self-correct; `user_message` says the same thing without API vocabulary. Clients that relay errors into a human surface (chat, email, UI) should show `user_message` when present and fall back to `detail`. example: >- ACH payments pay out USD, so a USDC payout isn't possible on this rail. Change the payout currency to USD and try again. reason: type: string description: > A stable, machine-readable code for why the request was refused, present only when Dakota has a typed reason for this error. Branch on `reason` rather than parsing `detail`. `detail` is unchanged. This is an open set: new values are added over time and a value is never repurposed, so treat an unrecognized `reason` as absent. Which operations return it today: - `createAccount` (onramp, offramp and swap) and `createTransaction` (a one-off transaction creates an account): every value in the table except `immutable_field`; `signature_required` comes from `createTransaction` only. - `updateAccount`: `field_invalid` (a developer fee that is out of range), `resource_not_found`, and `immutable_field` (the change would alter the account's routing; create a new account instead). - `deleteAccount`: `resource_not_found`. - `createInstructions`: a payment-agent instruction that creates an account fails with the same `reason` values as `createAccount`, but `params.field` is never returned there: the response carries the other `params` keys only, because this operation has no public field names to map to. - Other operations may also set `reason`. Treat a `reason` you do not recognize as absent, as above, and never assume an operation that is not listed here omits it. | `reason` | Meaning | `params` | | --- | --- | --- | | `field_required` | A required request field is missing. | `field` | | `field_invalid` | A field is present but unusable. | `field`, `constraint`, `rail` | | `field_too_long` | A field is longer than the rail allows. | `field`, `max`, `actual`, `rail` | | `field_too_short` | A field is shorter than the rail allows. | `field`, `min`, `actual` | | `address_incomplete` | An address lacks parts the route needs. | `subject`, `fields` | | `unsupported_network` | The network is not supported. | `network` | | `unsupported_asset` | The asset does not exist on the network. | `asset`, `network` | | `no_route_available` | No payment route covers the request. | `direction`, `rail`, `currency`, `network` | | `onboarding_required` | The customer has not completed onboarding for a capability. | `capability` | | `entity_not_active` | Onboarding for a capability exists but is not yet usable. | `capability`, `status` | | `destination_unreachable` | The destination cannot be reached over the requested rail. | `rail`, `alternative`, `direction` | | `limit_exceeded` | An amount exceeds a ceiling. | `limit`, `max`, `configured`, `currency` | | `resource_not_found` | The named resource does not exist. | `resource` | | `duplicate_resource` | A matching resource already exists. | `resource` | | `request_rejected` | The request was refused and the reason is not disclosed. | none | | `signature_required` | The request must be signed. | none | | `immutable_field` | The field cannot be changed on an existing account; create a new one. | none | example: field_too_long params: type: object description: | Parameters of `reason`. Every value is a string: a number, a token from a closed set, or the public name of a request field (`field` is expressed in this operation's request body, and is omitted when the offending value has no public name). Never free text. Present only alongside `reason`, and only when the reason has parameters. additionalProperties: type: string example: field: payment_reference max: '35' actual: '40' rail: swift PersonName: type: object description: Full name of a person required: - first - last properties: first: type: string description: First name example: John middle: type: string description: Middle name (optional) example: Michael last: type: string description: Last name example: Doe Address: type: object title: Address description: >- Standardized physical address format used throughout the Dakota platform for user and entity addresses. required: - street1 - city - country properties: street1: type: string description: Primary street address line example: 123 Main St street2: type: string description: >- Secondary address information such as apartment, suite, or unit number example: Apt 4B street3: type: string description: Additional address information like building name or floor example: Building C city: type: string description: City or locality name example: San Francisco region: type: string description: > State, province or region. Send the subdivision part of its ISO 3166-2 code, the characters after the country prefix, rather than the full name: for example `CA` for California (`US-CA`) or `ON` for Ontario (`CA-ON`). The onboarding endpoints (business details and individuals on an application) require a region for a US address and accept only a two-letter US state or territory code there, rejecting a full name such as `California`. example: CA postal_code: type: string description: Postal or ZIP code example: '94105' country: type: string description: ISO 3166-1 alpha-2 country code (two-letter country code) example: US minLength: 2 maxLength: 2 ApplicationStatus: type: string title: Application Status description: > Current status of an application in the onboarding flow. Status flow: - `pending` - Initial state, not yet submitted - `submitted` - Submitted for verification - `under_review` - Being reviewed by compliance team - `request_for_information` - Admin requesting additional info/documents from applicant - `admin_revision` - Admin making corrections to application data - `approved` - Application approved - `declined` - Application declined - `completed` - Legacy status (deprecated, use approved/declined instead) - `compliance_review` - Application is awaiting compliance review of a Proof of Address document. Set when an individual applicant uploads a PoA-equivalent document (proof_of_address, bank_statement, or utility_bill) after their application has already been approved or completed. The customer remains active but is subject to the $3,000 USD-equivalent rolling 7-day transaction limit until the review concludes. - `closed` - Compliance took the application out of review without a decision. It may be reopened to `under_review` by compliance. enum: - pending - submitted - under_review - request_for_information - admin_revision - approved - declined - completed - compliance_review - closed example: submitted AssociatedIndividualEntity: allOf: - $ref: '#/components/schemas/IndividualEntity' - type: object description: >- Individual associated with a business (extends IndividualEntity with role information) required: - roles properties: roles: type: array description: Role(s) of this individual in relation to the business items: type: string enum: - ubo - control_person - authorized_representative - applicant minItems: 1 example: - ubo - control_person ownership_percentage: type: number format: double description: Ownership percentage (optional, typically provided for UBO role) minimum: 0 maximum: 100 example: 25.5 title: type: string description: Job title example: CEO 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 IndividualEntity: type: object description: Individual entity data (entity information only, no validation) required: - id - first_name - last_name - date_of_birth - nationalities - address - email_address properties: id: type: string format: ksuid description: >- Individual applicant identifier (this is the applicant_id, NOT the internal individual entity ID) example: 2hCjxJzUAW6JVRkZqaF9E0KpM3b first_name: type: string description: First name example: John last_name: type: string description: Last name example: Doe date_of_birth: type: string format: date description: Date of birth example: '1985-06-15' nationalities: type: array description: ISO 3166-1 alpha-2 country codes for nationalities minItems: 1 items: type: string minLength: 2 maxLength: 2 example: - US address: $ref: '#/components/schemas/Address' description: Residential address email_address: type: string description: >- Email address. May be empty if the applicant has not provided one yet. example: john.doe@acme.com phone_number: type: string description: Phone number (optional) example: +1-555-123-4567 employment_status: type: string description: Employment status (for individual person type only) enum: - employed - self_employed - unemployed - student - retired example: employed purpose_of_account: type: array description: Intended purposes for the account (for individual person type only) items: type: string enum: - investing - sending_and_receiving_payments - storage_of_funds_or_digital_assets - making_online_payments - trading_on_other_platforms example: - investing - storage_of_funds_or_digital_assets source_of_wealth: type: array description: Sources of wealth (for individual person type only) items: type: string enum: - investments - employment - court_settlement - lottery_winnings - retirement_income - savings - sale_of_assets - family_funds - gambling_winnings - gift - inheritance - insurance_claim - loan - redundancy_severance - benefits example: - employment - savings ssn: type: string description: >- Social Security Number for US persons, format XXX-XX-XXXX. Dakota stores it, but client-facing application responses do not return it. Only Dakota compliance reviewers can see it. pattern: ^\d{3}-\d{2}-\d{4}$ example: 123-45-6789 decision: type: string enum: - approved - declined - auto_declined - withdrawn nullable: true description: Decision on this individual entity (if made) example: approved decision_reason: type: string nullable: true description: > Reason for the decision, as the reviewer wrote it. Compliance-facing: omitted for callers without compliance review permission. example: All verification checks passed decision_by: type: string nullable: true description: | Email of admin who made the decision. Compliance-facing: omitted for callers without compliance review permission. example: admin@dakota.xyz decision_at: type: integer format: int64 nullable: true description: Unix timestamp when decision was made example: 1705315800 decline_reason: allOf: - $ref: '#/components/schemas/DeclineReason' description: >- The client-visible category, when this entity is declined and one was recorded. sumsub_verification: $ref: '#/components/schemas/SumsubReviewData' description: Sumsub verification data for this individual entity DeclineReason: type: string title: Decline Reason description: > The category of a declined application that may be shared with the client and the applicant. It is the whole of what is shared: the reviewer's notes and the internal decision text are never returned. - `unsupported_region` - the applicant is located in a region Dakota does not currently support - `prohibited_country` - a country of incorporation, address or nationality is not supported - `prohibited_business_type` - the industry, legal structure or ownership form is not eligible - `other` - the application does not meet Dakota's onboarding requirements; no further detail is available Each value has a fixed `decline_message` you can show as is. Automatic declines set the category from the rule that fired; manual declines carry the category the reviewer selected, or `other` when none was. Declines recorded before this field existed have no category. enum: - unsupported_region - prohibited_country - prohibited_business_type - other example: prohibited_country SumsubReviewData: type: object description: Sumsub review information for a specific entity required: - applicant_id - provider_applicant_id - entity_type properties: applicant_id: type: string format: ksuid description: >- Dakota applicant ID (business_applicant_id or individual_applicant_id) example: 2hCjxJzUAW6JVRkZqaF9E0KpM3b provider_applicant_id: type: string description: Sumsub's applicant ID example: 65a1b2c3d4e5f6g7h8i9j0k1 entity_type: type: string enum: - business - individual description: Type of entity example: individual type: type: string description: Sumsub applicant type (e.g., 'company', 'individual') example: individual decision: type: string enum: - approved - declined - auto_declined - withdrawn nullable: true description: Current decision from Dakota database example: approved decision_reason: type: string nullable: true description: Reason for the decision example: All verification checks passed decision_by: type: string nullable: true description: Email of user who made the decision example: admin@dakota.xyz decision_at: type: integer format: int64 nullable: true description: Unix timestamp when decision was made example: 1705315800 review: $ref: '#/components/schemas/SumsubReview' description: Sumsub verification review details risk_labels: $ref: '#/components/schemas/SumsubRiskLabels' description: Risk labels identified by Sumsub SumsubReview: type: object description: Sumsub verification review details properties: review_id: type: string description: Unique review identifier example: 65a1b2c3d4e5f6g7h8i9j0k1 attempt_id: type: string description: Verification attempt identifier example: 65a1b2c3d4e5f6g7h8i9j0k2 attempt_cnt: type: integer description: Number of verification attempts example: 1 level_name: type: string description: Verification level name example: basic-kyc-level create_date: type: string description: When review was created (ISO 8601) example: '2024-01-15T10:30:00Z' review_date: type: string nullable: true description: When review was completed (ISO 8601) example: '2024-01-15T14:45:00Z' review_status: type: string enum: - init - pending - prechecked - queued - completed - onHold description: Current status of the review example: completed review_result: $ref: '#/components/schemas/SumsubReviewResult' description: Sumsub review result details SumsubRiskLabels: type: object description: Risk labels identified by Sumsub properties: device: type: array items: type: string description: Device-related risk indicators example: - EMULATOR - VPN cross_check: type: array items: type: string description: Cross-check risk indicators example: - FAKE_ID - BLACKLIST attempt_id: type: string description: Associated attempt ID example: 65a1b2c3d4e5f6g7h8i9j0k2 created_at: type: string description: When risk labels were created example: '2024-01-15T10:30:00Z' SumsubReviewResult: type: object description: Sumsub review result details properties: review_answer: type: string enum: - GREEN - RED - YELLOW description: Review outcome (GREEN = passed, RED = failed, YELLOW = needs review) example: GREEN reject_labels: type: array items: type: string description: Reasons for rejection if review_answer is RED example: - DOCUMENT_TEMPLATE - FRAUDULENT_PATTERNS reject_type: type: string description: Type of rejection example: FINAL button_ids: type: array items: type: string description: IDs of buttons clicked during review example: - approve moderation_comment: type: string description: Comment from Sumsub moderator example: All documents verified successfully client_comment: type: string description: Client comment on the review example: Approved for onboarding securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ApplicationTokenAuth: type: apiKey in: header name: X-Application-Token description: > Application-specific token for public URL access. Generated when a customer is created. Provides access to a single application without requiring an API key. Token is valid for 90 days and rate-limited to 250 requests per hour. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.