Client accounts · Ready Docs

#Client accounts

For agencies running one Ready account per customer. Each client account has its own numbers, 10DLC registration, card and balance, and pays for its own texts.

Details

Call these with an rsms_ key from your own account.

Two kinds of sub-account. An independent sub-account (account_kind: "client") pays from its own card and balance. A Workspace in the guides is different: your main account's balance pays for it.

Markup and how you're paid

Markup can't be set anymore: any markup above 0 is refused with 400. Set your clients' prices with partner fees on the Partner page. It's in the Agency view: click your business name in the top bar, then Agency view. A client that already pays a markup keeps paying it, as described below.

Details

Price: a client pays your base rate plus your markup per segment (Set a client's markup).
Payout: markup goes to your reseller balance, only for texts a client sends after it submits its 10DLC registration. Earlier texts aren't credited later. You earn no affiliate commission on your own clients.

Acting as a client

Add X-Sub-Account-Id: <client id> to any /v1 API-key request to run it as that client: what you create is the client's, and its card and balance pay.

Details

The key can be sent as X-API-Key or Authorization: Bearer. Your own numbers aren't visible while you act as a client. Buy with POST /v1/numbers/checkout, not /phone-numbers/checkout.

Buy a number for a client: POST /v1/numbers/checkout then POST /v1/numbers, both with the header (a payment your own account made also works for the second call). Then poll GET /v1/numbers/:id, with the header, until it's active.

Refusals (nothing runs):

HTTP	Code	Meaning
400	`invalid_sub_account_id`	Not a numeric id (also `0` or empty).
400	`sub_account_header_not_supported`	Path outside `/v1`.
400	`sub_account_header_needs_api_key`	No `rsms_` API key.
403	`sub_account_forbidden`	Not a client you manage (including your own id).
403	`sub_account_suspended`	Client suspended.
404	`sub_account_not_found`	No account has that id.
503	`AUTH_CHECK_UNAVAILABLE`	Couldn't check. Nothing ran; retry.

GET /v1/numbers as a client

curl "https://api.tryready.com/v1/numbers" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "X-Sub-Account-Id: 4812"

const res = await fetch('https://api.tryready.com/v1/numbers', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'X-Sub-Account-Id': '4812',
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/numbers",
    headers={"X-API-Key": os.environ["READY_API_KEY"], "X-Sub-Account-Id": "4812"},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

#Create a client account

POST/v1/sub-accounts

Creates a client account with its own login, card, numbers and registration.

Auth API key with team management
Cost Free

Body parameters

emailstringRequired: The client owner's email.
first_name, last_namestringOptional
company_namestringOptional
send_invitebooleanOptionalDefault true: Emails the client an invite to set up their login and card.
Details
Send false to skip the email and send them invite_link yourself.
billingstringOptionalDefault client: client: the client adds their own card and pays their own bill. agency: your card pays for the client’s registration, numbers and messages, at your prices.

Returns

dataobject: id (use it as X-Sub-Account-Id), email, company_name, account_kind: "client", client_rate, invite_link.
Details
client_rate is what the client pays per segment (your base rate plus your default markup). It's null unless your markup is on and your default markup is above 0.

Errors

HTTP	Code	When
400	`invalid_request`	Missing `email`.
400	`unknown_field`	A field it doesn't accept.
403	`agency_only`	Your account is another agency's client or workspace.
409	`client_already_yours`	Already your client.
409	`email_reserved`	Email can't be used (403 for a staff address).

POST /v1/sub-accounts

curl -X POST "https://api.tryready.com/v1/sub-accounts" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@client-a.example.com",
    "company_name": "Client A Dental",
    "send_invite": false
  }'

const res = await fetch('https://api.tryready.com/v1/sub-accounts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "owner@client-a.example.com",
    "company_name": "Client A Dental",
    "send_invite": false
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/sub-accounts",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "email": "owner@client-a.example.com",
        "company_name": "Client A Dental",
        "send_invite": False
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "id": 4812,
    "email": "owner@client-a.example.com",
    "company_name": "Client A Dental",
    "account_kind": "client",
    "client_rate": null,
    "invite_link": "https://app.tryready.com/team-welcome?token=…"
  }
}

#List client accounts

GET/v1/sub-accounts

The client accounts you manage, newest first. Pages with a cursor.

Auth API key with team management
Cost Free

Query parameters

limitintegerOptionalDefault 50Max 200: Page size.
before_idintegerOptional: The next_before_id from the previous page.

Returns

data[]object[]: id, email, first_name, last_name, company_name, status, markup_usd_per_segment, created_at.
has_moreboolean: Today it's true on any full page, even if nothing follows. Page until data is empty.
next_before_idinteger | null: Pass as before_id.

Errors

HTTP	Code	When
403	`permission_denied`	The key lacks team management (all four endpoints).

GET /v1/sub-accounts

curl "https://api.tryready.com/v1/sub-accounts?limit=200" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/sub-accounts?limit=200', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/sub-accounts",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    params={
        "limit": 200
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": [
    {
      "id": 4812,
      "email": "owner@client-a.example.com",
      "first_name": "Sam",
      "last_name": "Rivera",
      "company_name": "Client A Dental",
      "status": "active",
      "markup_usd_per_segment": 0.004,
      "created_at": "2026-09-14T16:20:05.118Z"
    }
  ],
  "has_more": false,
  "next_before_id": 4812
}

#Get a client account

GET/v1/sub-accounts/:id

One client account.

Auth API key with team management
Cost Free

Path parameters

idintegerRequired: The client account id.

Errors

HTTP	Code	When
404	`sub_account_not_found`	Not a client you manage.

GET /v1/sub-accounts/:id

curl "https://api.tryready.com/v1/sub-accounts/4812" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/sub-accounts/4812', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/sub-accounts/4812",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "id": 4812,
    "email": "owner@client-a.example.com",
    "first_name": "Sam",
    "last_name": "Rivera",
    "company_name": "Client A Dental",
    "status": "active",
    "markup_usd_per_segment": 0.004,
    "created_at": "2026-09-14T16:20:05.118Z"
  }
}

#Set a client's markup

PUT/v1/sub-accounts/:id/rate

What the client pays you per segment on top of your own rate. Any markup above 0 is refused now; set prices with partner fees on the Partner page, in the Agency view.

Auth API key with team management
Cost Free

Path parameters

idintegerRequired: The client account id.

Body parameters

markupnumberOptional: Dollars per segment, from 0 to 0.06.
use_defaultbooleanOptional: true to use your default markup instead.
dialer_markup, use_default_dialernumber, booleanOptional: The same, for calls.

Returns

dataobject: markup, is_custom, base_rate (your rate), client_rate (the client's per-segment price).

Errors

HTTP	Code	When
400	`invalid_request`	Negative markup, or nothing to change.
400	`unknown_field`	A field it doesn't accept.
400	`terms_required`	Reseller terms not accepted.
400	`invalid_markup`	Above $0.06 a segment.
403	`reseller_not_approved`	Markup above 0, setup under review.
403	`forbidden`	Markup above 0 while markup is off, or not your main account.
404	`sub_account_not_found`	Not a client you manage.
409	`rate_locked`	Rate locked; contact support.

PUT /v1/sub-accounts/:id/rate

curl -X PUT "https://api.tryready.com/v1/sub-accounts/4812/rate" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markup": 0.004
  }'

const res = await fetch('https://api.tryready.com/v1/sub-accounts/4812/rate', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "markup": 0.004
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/v1/sub-accounts/4812/rate",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "markup": 0.004
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "markup": 0.004,
    "is_custom": true,
    "base_rate": 0.02,
    "client_rate": 0.024
  }
}