White-label sub-accounts

Before you start

The white-label API is part of the Enterprise plan. An account that has never had white-label gets 403 PLAN_UPGRADE_REQUIRED from every route on this page; one that had it and still owns sub-accounts keeps the few routes that wind them down (below). Sub-accounts are managed through these routes only: the dashboard's Settings → White-label page sets your branding, not your sub-accounts.

• A sub-account's key works like any Kawaa API key: send it in X-Api-Key to the verification endpoints, and its requests spend the sub-account's credits, never yours. The same key signs the sub-account into the dashboard with the sign-in page's API key option.
• Reading sub-accounts needs the white_label:read scope; changing, deleting and funding them needs white_label:write. The usage routes need white_label:read and analytics:read. Creating a sub-account and resetting its key both return a new API key, so they need an unrestricted key or a signed-in session; a scoped key gets 403 INSUFFICIENT_SCOPE.
• Each change you make here is in your account's audit log: creating, changing or deleting a sub-account, allocating or reclaiming credits, resetting a sub-account's key, and changing your white-label settings. An entry names the sub-account by its ID and the API key, session or connected app that made the change, never a sub-account's API key or email address. A key reset is also in the sub-account's own audit log, which names your account only as the account that manages it.
• You can have up to 100 sub-accounts at a time unless your account has a different limit. The limit holds for creates sent in parallel too: past it, each one answers 400 and nothing is created or charged.
• A sub-account gets what your plan includes and never more: the same features, batch size, result retention and other limits as your own account, following your plan when it changes. Its requests per minute (its rate_limit times your rate-limit multiplier) stop at your own plan's limit, and a rate_limit above what fits answers 400 with the most you can set.

How sub-account credits work

• Credits come out of your balance. Allocating credits to a sub-account, when you create it or later with Allocate credits, moves them from your own balance into the sub-account's pool. Reclaiming moves unused credits back, and deleting a sub-account returns whatever is left in its pool.
• Allocations count as credits you used. Credits you move into a sub-account count toward your own used credits (credits_used) for your current billing period, the same as credits you spend yourself. Reclaiming them or deleting the sub-account takes them back off, up to what you moved in during that period.
• Every move is on both statements. Each allocation, reclaim and returned balance is a transfer row in credit transactions (GET /v1/usage/credits/transactions): on yours, naming the sub-account's email with its ID in reference_id; on the sub-account's own, read with its key. Both rows are written in the same step as the two balances, each with the balance_after it left, so either ledger adds up to its balance. ?type=transfer lists only these.
• The pool never resets. A sub-account has no monthly allowance of its own. When its balance runs out, its verification requests are refused with 402 INSUFFICIENT_CREDITS until you allocate more.
• You are told before it runs out. When a sub-account's balance falls to 20% of the credits allocated to it, and again when it drops below 1 credit (the price of a fresh check), we email your account address (if your low-credit and credits-exhausted email notifications are on) and send credits.low or credits.exhausted to your registered webhooks, with "account_type": "sub_account" and the sub-account's ID and name in the payload.

Create a sub-account

Request body

Any other field answers 400 and creates nothing, so a misspelled rate_limit cannot quietly fall back to the default.

curl -X POST https://api.kawaa.com/v1/white-label/sub-accounts \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ops@northwind.example",
    "name": "Northwind Retail EU",
    "credits_allocated": 5000
  }'

{
  "success": true,
  "data": {
    "sub_account": {
      "sub_account_id": "sub_3f9a1c7e5b2d8a64",
      "email": "ops@northwind.example",
      "name": "Northwind Retail EU",
      "api_key": "ev_aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY",
      "credits_allocated": 5000,
      "credits_balance": 5000,
      "rate_limit": 100,
      "status": "active",
      "created_at": "2026-09-21T10:15:30.412Z"
    },
    "warning": "Save the API key now. You will not be able to see it again."
  }
}

List sub-accounts

Every sub-account you have not deleted, suspended ones included.

{
  "success": true,
  "data": {
    "sub_accounts": [
      {
        "sub_account_id": "sub_3f9a1c7e5b2d8a64",
        "email": "ops@northwind.example",
        "name": "Northwind Retail EU",
        "status": "active",
        "credits_allocated": 5000,
        "credits_used": 4210,
        "credits_balance": 790,
        "rate_limit": 100,
        "created_at": "2026-09-21T10:15:30.412Z",
        "updated_at": "2026-09-21T10:15:30.412Z"
      }
    ],
    "total": 1
  }
}

credits_allocated is the running total you have moved in, less anything you reclaimed. credits_balance is what the sub-account can still spend, and credits_used is what it has spent.

Get a sub-account

The same fields as the list, plus last_reset_at (when the sub-account was created).

Update a sub-account

Send at least one of these fields. Credits never move through this route; use Allocate credits.

The read-only fields a GET returns (email, the credit fields, timestamps) are accepted and ignored, so you can send back an object you read. Any other field answers 400 and changes nothing. A sub-account deleted while the update was in flight answers 404 and stays deleted.

curl -X PUT https://api.kawaa.com/v1/white-label/sub-accounts/sub_3f9a1c7e5b2d8a64 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "suspended"}'

{
  "success": true,
  "data": {
    "sub_account": {
      "sub_account_id": "sub_3f9a1c7e5b2d8a64",
      "email": "ops@northwind.example",
      "name": "Northwind Retail EU",
      "status": "suspended",
      "credits_allocated": 5000,
      "credits_used": 4210,
      "credits_balance": 790,
      "rate_limit": 100,
      "updated_at": "2026-09-21T11:02:08.905Z"
    },
    "message": "Sub-account updated"
  }
}

Allocate credits

Move credits from your balance into an active sub-account's pool. The credits leave your balance and arrive in the sub-account in the same step, so neither side can change without the other. A negative number moves unused credits the other way, from the sub-account back to your balance.

curl -X POST https://api.kawaa.com/v1/white-label/sub-accounts/sub_3f9a1c7e5b2d8a64/allocate \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credits": 2000}'

{
  "success": true,
  "data": {
    "sub_account": {
      "sub_account_id": "sub_3f9a1c7e5b2d8a64",
      "credits_allocated": 7000,
      "credits_balance": 2790
    },
    "message": "Allocated 2000 credits"
  }
}

A reclaim answers "message": "Reclaimed 500 credits" and lowers both credits_allocated and credits_balance. You cannot reclaim more than the sub-account's current balance; to empty it, reclaim exactly that, or delete the sub-account.

• Your balance smaller than credits: 402 INSUFFICIENT_CREDITS, and nothing moves.
• A suspended sub-account: 400. Set it back to active first, or delete it to get its balance back.
• Suspended or deleted while the allocation ran: 409 CONFLICT, and your balance is untouched.

Reset a sub-account's key

Revoke every active key the sub-account has and issue a new one. Requests with the old key stop working straight away. Needs an unrestricted key or a signed-in session. One reset runs at a time for each sub-account: a second request sent while the first is still running (a retry of a slow response, say) answers 409 CONFLICT and changes nothing. Retry it once the first has finished, and use the key the latest successful reset returned. The route reads no request body; one carrying any field answers 400 and resets nothing.

{
  "success": true,
  "data": {
    "sub_account_id": "sub_3f9a1c7e5b2d8a64",
    "api_key": "ev_Zx8Wv6Ut4Sr2Qp0On8Ml6Kj4Ih2Gf0Ed",
    "warning": "Save this API key now. You will not be able to see it again."
  }
}

Delete a sub-account

Close the sub-account and return its unused credits to your balance in the same step. Its key stops working, and its email address can be used for a new sub-account. A refund that comes later for work it was charged for before the delete, such as a domain search that finishes with some addresses unchecked, is added to your balance too. The route reads no request body; one carrying any field answers 400 and deletes nothing.

{
  "success": true,
  "data": {
    "message": "Sub-account deleted",
    "sub_account_id": "sub_3f9a1c7e5b2d8a64",
    "credits_returned": 790
  }
}

Sub-account usage

Current credit figures for every sub-account, with totals. GET /v1/white-label/analytics returns the same thing. These are balances right now, not a time series, so a period query parameter answers 400.

{
  "success": true,
  "data": {
    "summary": {
      "total_sub_accounts": 1,
      "total_credits_allocated": 7000,
      "total_credits_used": 4210,
      "total_credits_balance": 2790
    },
    "sub_accounts": [
      {
        "sub_account_id": "sub_3f9a1c7e5b2d8a64",
        "name": "Northwind Retail EU",
        "email": "ops@northwind.example",
        "credits_allocated": 7000,
        "credits_used": 4210,
        "credits_balance": 2790,
        "usage_percentage": 60
      }
    ]
  }
}

One sub-account

The same figures for one sub-account, as top-level fields, plus last_reset_at. usage_percentage is credits_used as a share of credits_allocated, rounded to a whole number.

Errors

Errors use the standard envelope described in Error codes. The ones these routes return: