A sub-client is a customer that has its own customers grouped underneath it. Use sub-clients when one of your customers is itself a business that onboards or serves its own end customers — for example a partner, reseller, or sub-developer building on top of your integration.

What is a sub-client?

Dakota organizes accounts in a three-level hierarchy:

Client (you)
└── Sub-Client            ← a business customer you designate at creation
    └── Customer          ← a regular customer associated with that sub-client
    └── Customer

Entity	Who it is	How it’s created
Client	You — the business integrating with Dakota (the holder of the API key).	Your Dakota account.
Sub-Client	A business customer of yours that, in turn, has its own customers.	`POST /customers` with `is_sub_client: true`.
Customer of a sub-client	A regular customer that belongs to one of your sub-clients.	`POST /customers` with `sub_client_id` set to the sub-client’s ID.

A sub-client is a real customer record: it completes the same KYB onboarding as any other business customer (see Customer Onboarding). The only difference is that other customers can be associated with it.

Because of their role, sub-clients are typically subject to enhanced due diligence (EDD) during compliance review. This may extend the time and documentation required to approve a sub-client compared to a regular business customer.

Rules & constraints

A sub-client must be a business customer (customer_type: "business"). Individuals cannot be sub-clients.
The sub-client designation is set at creation only and is immutable — a regular customer cannot be promoted to a sub-client later, and a sub-client cannot be demoted.
is_sub_client and sub_client_id are mutually exclusive on a single POST /customers request — a customer is either a sub-client or a customer of a sub-client, never both.
A sub_client_id must reference a customer that belongs to your client and is itself a sub-client.
The hierarchy is one level deep — a customer of a sub-client cannot itself be a sub-client.

Step 1: Create a sub-client

Create the sub-client like any business customer, with is_sub_client: true.

cURL

curl -X POST https://api.platform.dakota.xyz/customers \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partner Corp",
    "customer_type": "business",
    "is_sub_client": true
  }'

JavaScript

const response = await fetch('https://api.platform.dakota.xyz/customers', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Partner Corp',
    customer_type: 'business',
    is_sub_client: true
  })
});

const subClient = await response.json();
console.log('Created sub-client:', subClient.id);

Python

import requests
import uuid

response = requests.post(
    'https://api.platform.dakota.xyz/customers',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Partner Corp',
        'customer_type': 'business',
        'is_sub_client': True
    }
)

sub_client = response.json()
print(f'Created sub-client: {sub_client["id"]}')

package main

import (
    "bytes"
    "net/http"

    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "name": "Partner Corp",
        "customer_type": "business",
        "is_sub_client": true
    }`)

    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/customers", body)
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")

    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Response:

{
  "id": "2ABCrqBHb3cTfLVkFSGmHZqdXYZ",
  "kyb_links": [],
  "application_id": "2WGC9cKv9P4K8eGzqY6qJ3Xz7Qm",
  "application_url": "https://apply.dakota.com/applications/2WGC9cKv9P4K8eGzqY6qJ3Xz7Qm?token=...",
  "application_expires_at": 1734567890000000000
}

The sub-client now onboards exactly like any other business customer: redirect it to the returned application_url (or build a custom flow) and monitor its kyb_status. See Customer Onboarding for the full flow and KYB status values.

Keep the returned id (2ABCrqBHb3cTfLVkFSGmHZqdXYZ above) — this is the sub-client’s customer ID, which you’ll pass as sub_client_id when adding customers to it.

Step 2: Add a customer to the sub-client

Create a customer as usual, but set sub_client_id to the sub-client’s ID. The customer can be a business or individual.

cURL

curl -X POST https://api.platform.dakota.xyz/customers \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "customer_type": "business",
    "sub_client_id": "2ABCrqBHb3cTfLVkFSGmHZqdXYZ"
  }'

JavaScript

const response = await fetch('https://api.platform.dakota.xyz/customers', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corp',
    customer_type: 'business',
    sub_client_id: '2ABCrqBHb3cTfLVkFSGmHZqdXYZ'
  })
});

const customer = await response.json();
console.log('Created customer under sub-client:', customer.id);

Python

import requests
import uuid

response = requests.post(
    'https://api.platform.dakota.xyz/customers',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Acme Corp',
        'customer_type': 'business',
        'sub_client_id': '2ABCrqBHb3cTfLVkFSGmHZqdXYZ'
    }
)

customer = response.json()
print(f'Created customer under sub-client: {customer["id"]}')

package main

import (
    "bytes"
    "net/http"

    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "name": "Acme Corp",
        "customer_type": "business",
        "sub_client_id": "2ABCrqBHb3cTfLVkFSGmHZqdXYZ"
    }`)

    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/customers", body)
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")

    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

This customer onboards through the standard flow. The association is fixed at creation — there is no endpoint to move a customer between sub-clients afterward.

The legacy PATCH /customers/{customer_id}/sub-client endpoint is deprecated and non-functional — it now rejects all requests with 400. Set sub_client_id on POST /customers instead.

Step 3: View sub-clients and their customers

Every customer record now carries three sub-client fields:

Field	Description
`is_sub_client`	`true` when this customer is itself a sub-client.
`sub_client_id`	The parent sub-client’s ID when this customer belongs to a sub-client; otherwise `null`.
`sub_client_name`	The parent sub-client’s name when this customer belongs to a sub-client; otherwise `null`.

List all your sub-clients

cURL

curl "https://api.platform.dakota.xyz/customers?is_sub_client=true" \
  -H "X-API-Key: your-api-key"

List the customers of a sub-client

Filter the customer list by sub_client_id to return only the customers associated with that sub-client.

cURL

curl "https://api.platform.dakota.xyz/customers?sub_client_id=2ABCrqBHb3cTfLVkFSGmHZqdXYZ" \
  -H "X-API-Key: your-api-key"

Get a sub-client summary

GET /customers/sub-client-summary returns every sub-client along with the number of customers associated with it — useful for dashboards and reporting.

cURL

curl "https://api.platform.dakota.xyz/customers/sub-client-summary" \
  -H "X-API-Key: your-api-key"

Response:

{
  "data": [
    {
      "sub_client_id": "2ABCrqBHb3cTfLVkFSGmHZqdXYZ",
      "sub_client_name": "Partner Corp",
      "customer_count": 15
    }
  ]
}

Next Steps

Customer Onboarding — the KYB flow every sub-client and customer completes
Webhook Integration — track KYB status changes for sub-clients and their customers
Testing — exercise sub-client creation in sandbox

API Reference

Create a customer record — is_sub_client and sub_client_id fields
List all customer records — is_sub_client and sub_client_id filters
Get sub-client summary

Playground

Documentation

Agentic Payments

Authentication

Developer Tools

Sub-Clients

What is a sub-client?

Rules & constraints

Step 1: Create a sub-client

Step 2: Add a customer to the sub-client

Step 3: View sub-clients and their customers

List all your sub-clients

List the customers of a sub-client

Get a sub-client summary

Next Steps

API Reference

​What is a sub-client?

​Rules & constraints

​Step 1: Create a sub-client

​Step 2: Add a customer to the sub-client

​Step 3: View sub-clients and their customers

​List all your sub-clients

​List the customers of a sub-client

​Get a sub-client summary

​Next Steps

​API Reference

What is a sub-client?

Rules & constraints

Step 1: Create a sub-client

Step 2: Add a customer to the sub-client

Step 3: View sub-clients and their customers

List all your sub-clients

List the customers of a sub-client

Get a sub-client summary

Next Steps

API Reference