> ## 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. # List all customer records > Returns a paginated list of customers for the authenticated client. Supports cursor pagination and optional `external_id` or `search` filters. ## OpenAPI ````yaml /openapi.yaml get /customers 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: /customers: get: tags: - Customers summary: List all customer records description: >- Returns a paginated list of customers for the authenticated client. Supports cursor pagination and optional `external_id` or `search` filters. operationId: listCustomers parameters: - $ref: '#/components/parameters/StartingAfterParam' - $ref: '#/components/parameters/EndingBeforeParam' - $ref: '#/components/parameters/LimitParam' - name: external_id in: query description: Filter customers by external ID required: false schema: type: string - name: search in: query description: Search customers by name, email, or customer ID (case-insensitive) required: false schema: type: string - name: kyb_status in: query description: Filter customers by KYB status (single value). required: false schema: $ref: '#/components/schemas/KybStatus' - name: kyb_statuses in: query description: >- Filter customers by one or more KYB statuses. Comma-separated list (e.g. `active,frozen`). required: false schema: type: string - name: kyc_statuses in: query description: | Filter customers by one or more effective KYC/B link statuses. Comma-separated list (e.g. `pending,in_review`). Values mirror the `KybLinkStatus` enum (`not_started`, `pending`, `in_review`, `approved`, `expired`, `rejected`). required: false schema: type: string - name: application_statuses in: query description: | Filter customers by one or more onboarding application statuses. Comma-separated list (e.g. `submitted,under_review`). Values mirror the `ApplicationStatus` enum. Customers without an application are excluded when this filter is set. required: false schema: type: string - name: sub_client_id in: query description: >- Filter customers by sub-client association. Returns only customers associated with the specified sub-client. required: false schema: $ref: '#/components/schemas/KSUID' - name: is_sub_client in: query description: >- When true, returns only customers that are sub-clients (designated as such at creation). When false or omitted, returns all customers. required: false schema: type: boolean - name: sort_by in: query description: Field to sort customers by. Defaults to `name`. required: false schema: type: string enum: - application_status - created_at - customer_type - id - kyb_status - kyc_status - name - name: sort_dir in: query description: Sort direction. Defaults to `asc`. required: false schema: type: string enum: - asc - desc - name: created_at_from in: query description: >- Filter customers created at or after this ISO 8601 datetime (e.g. 2024-01-01T00:00:00Z). required: false schema: type: string format: date-time - name: created_at_to in: query description: >- Filter customers created at or before this ISO 8601 datetime (e.g. 2024-12-31T23:59:59Z). required: false schema: type: string format: date-time responses: '200': description: List of all customer records content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/Customer' meta: $ref: '#/components/schemas/Meta' example: data: - id: 1NFHrqBHb3cTfLVkFSGmHZqdDPi name: Acme Corp email: contact@acmecorp.com external_id: external_customer_123 customer_type: business kyb_status: pending kyc_status: pending kyb_links: - provider_id: trm_labs link_type: persona url: https://verify.provider.com/kyb/a1b2c3d4e5f6 status: pending created_at: 1234567890 updated_at: 1234567890 expires_at: 1234567890 deleted_at: 1234567890 provider_statuses: - provider_id: trm_labs status: approved endorsements: - string application_id: 1NFHrqBHb3cTfLVkFSGmHZqdDPi decision: approved application_url: >- https://onboarding.example.com/applications/abc123?token=xyz789 created_at: 1234567890 updated_at: 1234567890 deleted_at: 1234567890 meta: total_count: 100 has_more_after: true has_more_before: false '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/customers 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/customers request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6 '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.dakota.xyz/api-reference/errors#forbidden title: Forbidden status: 403 detail: Forbidden instance: https://api.platform.dakota.xyz/customers request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6 default: description: Unexpected error externalDocs: description: Read full guide in docs url: >- https://docs.dakota.xyz/api-reference/customers/list-all-customer-records components: parameters: StartingAfterParam: name: starting_after in: query required: false description: >- A cursor for use in pagination. `starting_after` is a KSUID for the object you are listing that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with ID `2B5J8KZ9N7M1K3P6Q8R4T7V9`, your subsequent call can include `starting_after=2B5J8KZ9N7M1K3P6Q8R4T7V9` in order to fetch the next page of the list. schema: $ref: '#/components/schemas/KSUID' EndingBeforeParam: name: ending_before in: query required: false description: >- A cursor for use in pagination. `ending_before` is a KSUID for the object you are listing that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with ID `2B5J8KZ9N7M1K3P6Q8R4T7V9`, your subsequent call can include `ending_before=2B5J8KZ9N7M1K3P6Q8R4T7V9` in order to fetch the previous page of the list. schema: $ref: '#/components/schemas/KSUID' LimitParam: name: limit in: query required: false description: >- A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. schema: type: integer minimum: 1 maximum: 100 default: 20 schemas: KybStatus: type: string description: >- Overall status of the KYB verification process (e.g., pending, active, restricted). example: pending enum: - active - pending - partner_review - rejected - frozen - auto_declined 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 Customer: type: object description: >- Response containing the current status of a KYB verification process including provider-specific statuses. required: - id - name - customer_type - kyb_status - kyc_status - created_at - updated_at properties: id: $ref: '#/components/schemas/KSUID' name: type: string description: Name of the customer example: Acme Corp email: type: string description: Email address of the customer example: contact@acmecorp.com external_id: type: string description: >- Unique identifier for the customer in the client's system, as supplied when the customer was created. Omitted when no external ID was set. example: external_customer_123 customer_type: type: string description: >- Type of entity - either an individual person or a company/organization enum: - individual - business example: business kyb_status: $ref: '#/components/schemas/KybStatus' kyc_status: allOf: - $ref: '#/components/schemas/KybLinkStatus' description: | Provider-agnostic effective KYC/B status for this customer, derived server-side for display convenience. Returns the same answer for both Sumsub-verified and Persona-verified customers without the client having to know which provider did the work. **Derivation order (most authoritative first):** 1. The customer's onboarding application `decision`, if set (`approved` → `approved`; `declined`/`auto_declined` → `rejected`; `withdrawn` → `expired`). 2. The most-recently-updated non-deleted persona `kyb_link`'s status (legacy customers from before the orchestration layer — Persona's `created` maps to `not_started`, `completed` to `approved`, `needs_review` to `in_review`). 3. `pending` if the customer has an open onboarding application but no decision yet (Sumsub in-flight). 4. `not_started` otherwise. **Advisory, not authoritative.** This field is provided for badge rendering and operator UIs. The derivation rules may evolve as new verification providers are added. For compliance-critical decisions, consult `decision`, `kyb_links`, and `provider_statuses` directly. kyb_links: type: array description: KYB Links for different providers used in the KYB process. items: $ref: '#/components/schemas/KybLink' provider_statuses: type: array description: >- Detailed status information from different verification providers used in the KYB process. items: $ref: '#/components/schemas/ProviderKybStatus' rd_allowed: type: boolean description: | Whether this customer is currently permitted to hold RD, derived server-side from the same US-state geofence that guards RD account creation. `true` when RD is allowed; `false` only when one of the customer's governing US states is on the restricted list while the geofence is active. Customers with no resolvable US governing state — non-US customers, or those whose jurisdiction is unconfirmed — are allowed. When the geofence is disabled (empty blocklist) this is `true` for everyone. This is the canonical read path for the RD-eligibility verdict: consumers read a boolean and never see or copy the underlying blocklist. example: true application_id: $ref: '#/components/schemas/KSUID' description: ID of the KYB application associated with this customer application_status: allOf: - $ref: '#/components/schemas/ApplicationStatus' description: | Current lifecycle state of the customer's onboarding application (e.g. `pending`, `submitted`, `under_review`, `approved`, `declined`). Omitted when the customer has no application. Use this field to drive workflow UI — it tracks where the customer is in the onboarding flow. For the orthogonal questions "is this customer cleared to transact?" and "what's the provider-agnostic KYC verdict?", see `kyb_status` and `kyc_status` respectively. decision: type: string description: Application decision status enum: - approved - declined - auto_declined - withdrawn example: approved application_url: type: string description: URL for accessing the onboarding application example: https://onboarding.example.com/applications/abc123?token=xyz789 created_at: type: integer description: Timestamp of when the link was created example: 1234567890 updated_at: type: integer description: Timestamp of when the link was last updated. example: 1234567890 deleted_at: type: integer description: Timestamp of when the link was deleted example: 1234567890 sub_client_id: $ref: '#/components/schemas/KSUID' description: ID of the sub-client this customer is associated with, if any. sub_client_name: type: string description: Name of the sub-client this customer is associated with, if any. example: Partner Corp is_sub_client: type: boolean description: >- Whether this customer is a sub-client. This is set when the customer is created and cannot be changed afterwards. default: false Meta: type: object description: Meta information about the response required: - total_count - has_more_after - has_more_before properties: total_count: type: integer description: Total number of items available example: 100 has_more_after: type: boolean description: Indicates whether there are more items that follow this set. example: true has_more_before: type: boolean description: Indicates whether there are more items that precede this set. example: false 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' KybLinkStatus: type: string title: KYB Link Status description: Current status of the KYB verification link. enum: - not_started - pending - expired - approved - rejected - in_review example: pending KybLink: type: object description: >- Link to the KYB verification portal or dashboard for a specific provider. required: - provider_id - link_type - url - status - created_at - updated_at properties: provider_id: type: string description: >- ID of the verification provider or service used for a specific check. example: trm_labs link_type: $ref: '#/components/schemas/KybLinkType' url: type: string description: >- URL link to the KYB verification portal or dashboard where the entity can complete the verification process. example: https://verify.provider.com/kyb/a1b2c3d4e5f6 status: $ref: '#/components/schemas/KybLinkStatus' created_at: type: integer description: Timestamp of when the link was created example: 1234567890 updated_at: type: integer description: Timestamp of when the link was last updated. example: 1234567890 expires_at: type: integer description: Timestamp of when the link will expire. example: 1234567890 deleted_at: type: integer description: Timestamp of when the link was deleted example: 1234567890 ProviderKybStatus: type: object required: - provider_id - status properties: provider_id: type: string description: >- ID of the verification provider or service used for a specific check. example: trm_labs status: type: string description: Current verification status with this specific provider. example: approved enum: - not_started - in_review - approved - rejected - requires_info - auto_declined - frozen endorsements: type: array items: type: string description: Array of endorsements associated with this provider status. 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. enum: - pending - submitted - under_review - request_for_information - admin_revision - approved - declined - completed - compliance_review example: submitted 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 KybLinkType: type: string title: KYB Link Type description: | Type of link provided by a verification provider for KYB verification. **Deprecated values:** - `tos` — the Bridge TOS flow has been deprecated. The dashboard no longer surfaces TOS state, but legacy customer records may still carry `link_type: 'tos'` entries on the wire. New integrations should ignore these entries; the value is retained in the enum to keep responses for legacy data schema-valid. enum: - persona - tos example: persona securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````