# Sub-accounts

Sub-accounts let a platform run signing for many customers from one place. Each customer gets an account with its own documents, branding and webhooks, and you reach all of them with your own key.

## Create one per customer

Call `create_account` with a name. Use a regular key from your main account. Agent keys can't create accounts, and a sub-account can't create its own.

```
curl https://docuinked.com/v1/accounts \
  -H "Authorization: Bearer $DOCUINKED_API_KEY" \
  -H "Idempotency-Key: customer-118" \
  -H "Content-Type: application/json" \
  -d '{"name": "Cedar Row Rentals"}'
```

```
{"status": "ok", "data": {"id": "acct_...", "name": "Cedar Row Rentals"}}
```

Store the `id` next to your own customer record. `list_accounts` (`GET /v1/accounts`) returns every sub-account with its `id`, `name` and `created_at`. The beta allows up to 1,000 sub-accounts per main account.

## Act for a customer

Add the header `DocuInked-Account` to any call. Everything in that call happens inside that sub-account: documents, templates, webhooks and branding.

```
curl https://docuinked.com/v1/documents \
  -H "Authorization: Bearer $DOCUINKED_API_KEY" \
  -H "DocuInked-Account: acct_..." \
  -H "Idempotency-Key: lease-2291" \
  -H "Content-Type: application/json" \
  -d '{"title": "Lease renewal",
       "pdf_url": "https://example.com/leases/2291.pdf",
       "signers": [{"name": "Dana Reed", "email": "dana@example.com"}]}'
```

Leave the header out and the call acts for your main account, as before. Name a sub-account that isn't yours and the call fails with `account_not_found`.

## Set each customer up

1. `create_account` for the customer.
2. `update_branding` with their `DocuInked-Account` header: their name, colour, logo, and the sites that may embed signing. See [branding](/docs/branding).
3. `create_webhook` with the same header, so their events go where you want them. See [webhooks](/docs/webhooks).
4. Send documents with the header, and show signing in your app with [embedded signing](/docs/embedded-signing).

## Keys, modes and safety

Your key's mode and send policy carry into every sub-account it acts for. A test key works in test mode there too, and emails no one. A live agent key still needs a person's approval for each send.

## Common questions

### Do my customers get their own logins?

No. Sub-accounts are run through your key. Your customers work inside your product and never sign in to docuinked.

### Can I move a document between sub-accounts?

No. A document stays in the account it was created in. To send the same file for another customer, create a new document with that customer's header.

### Do the beta limits apply per sub-account?

Write to support@docuinked.com before you onboard many customers, and we'll set limits that fit. The current numbers are on the [pricing page](/pricing).