> ## 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.

# Sub-Clients

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](/documentation/customer-onboarding)). The only difference is that other customers can be associated with it.

<Note>
  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.
</Note>

## Rules & constraints

<Warning>
  * 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.
</Warning>

# Step 1: Create a sub-client

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

```bash cURL theme={null}
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 JavaScript theme={null}
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 Python theme={null}
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"]}')
```

```go Go theme={null}
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:

```json theme={null}
{
  "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](/documentation/customer-onboarding) for the full flow and KYB status values.

<Info>
  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.
</Info>

# 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`.

```bash cURL theme={null}
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 JavaScript theme={null}
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 Python theme={null}
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"]}')
```

```go Go theme={null}
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.

<Warning>
  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.
</Warning>

# 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

```bash cURL theme={null}
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.

```bash cURL theme={null}
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.

```bash cURL theme={null}
curl "https://api.platform.dakota.xyz/customers/sub-client-summary" \
  -H "X-API-Key: your-api-key"
```

Response:

```json theme={null}
{
  "data": [
    {
      "sub_client_id": "2ABCrqBHb3cTfLVkFSGmHZqdXYZ",
      "sub_client_name": "Partner Corp",
      "customer_count": 15
    }
  ]
}
```

# Next Steps

1. **[Customer Onboarding](/documentation/customer-onboarding)** — the KYB flow every sub-client and customer completes
2. **[Webhook Integration](/documentation/webhooks)** — track KYB status changes for sub-clients and their customers
3. **[Testing](/documentation/testing)** — exercise sub-client creation in sandbox

# API Reference

* [Create a customer record](/api-reference/customers/create-a-customer-record) — `is_sub_client` and `sub_client_id` fields
* [List all customer records](/api-reference/customers/list-all-customer-records) — `is_sub_client` and `sub_client_id` filters
* [Get sub-client summary](/api-reference/customers/get-sub-client-summary)