Team members

The people who sign in to an account, each with their own login and role. Call these with your own key, and add X-Sub-Account-Id to work on a sub-account’s team. Sub-accounts themselves are on Sub-accounts.

#Add a team member

Adds a person to the team, with their own login and an invite email with a sign-in link. With X-Sub-Account-Id it’s that sub-account’s team. Needs the Manage team permission (invite_team).

Parameters

emailstringRequired: Their login email. The invite goes here.
first_name, last_namestring
roleenumDefault admin: admin: everything, billing and team included (Admin on the Team page). member: send texts and work with contacts and reports, but can’t buy numbers or spend money (Member). viewer: read only. agent: a member who also uses the dialer, which needs a free dialer seat; the Team page shows it as Member. The Team page preset Full teammate has no value here. Left out, role is admin, which includes billing: send member unless the person should manage billing and the team.
sub_account_accessenum: all: they can also open your sub-accounts. organization_only: they work in your main account only. Left out, Ready picks it the way the Team page does.
X-Sub-Account-Idinteger · header: The sub-account to add them to. Leave it out to add them to your own account.

Returns 201 with data.id (their user id) and data.email.

Errors

HTTP	Code	When
400	`invalid_request`	Missing `email`, or a `role` not in the list.
400	`unknown_field`	A field it doesn’t accept.
400	`already_on_team`	They’re already on this team, or it’s the owner’s email. Nothing to do.
403	`permission_grant_exceeds_your_own`	The role has more access than the key’s user.
403	`sub_account_forbidden`	Not a sub-account you manage. Nothing was added.
403	`forbidden`	No dialer seat free for an `agent`.
403	`permission_denied`	The key’s user can’t manage the team.
500	`internal_error`	It may or may not have been added. Check the team in Ready before you send it again.

curl -X POST "https://api.tryready.com/v1/team-members" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "frontdesk@brightsmile.example.com",
    "first_name": "Casey",
    "last_name": "Ng",
    "role": "admin"
  }'

const res = await fetch('https://api.tryready.com/v1/team-members', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "frontdesk@brightsmile.example.com",
    "first_name": "Casey",
    "last_name": "Ng",
    "role": "admin"
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/team-members",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "email": "frontdesk@brightsmile.example.com",
        "first_name": "Casey",
        "last_name": "Ng",
        "role": "admin"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "id": 4813,
    "email": "frontdesk@brightsmile.example.com"
  }
}

#List team members

The people on the team, newest first, as the Team page lists them. Sub-accounts aren’t in it: use List sub-accounts. With X-Sub-Account-Id it’s that sub-account’s team. Needs the Manage team permission (invite_team).

Returns

data[]object[]: One per person: id, email, first_name, last_name, role, status, invite_status (pending until they sign in the first time, then active), invite_expired, sub_account_access, holds_dialer_seat and created_at.

Errors

HTTP	Code	When
403	`permission_denied`	The key’s user can’t manage the team.
500	`internal_error`	The list couldn’t be read. Retry.

curl "https://api.tryready.com/v1/team-members" \
  -H "X-API-Key: $READY_API_KEY"

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

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/team-members",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [
    {
      "id": 5120,
      "email": "frontdesk@brightsmile.example.com",
      "first_name": "Casey",
      "last_name": "Ng",
      "role": "admin",
      "status": "active",
      "invite_status": "pending",
      "invite_expired": false,
      "sub_account_access": "all",
      "holds_dialer_seat": false,
      "created_at": "2026-11-03T18:20:11.004Z"
    }
  ]
}

#Update a team member

Changes a person’s name, role or sub-account access. Send only what you want to change. A role change signs them out, so their next sign-in has the new access. Needs the Manage team permission (invite_team).

Parameters

idinteger · pathRequired: Their id from List team members.
first_name, last_namestring
roleenum: The same roles as Add a team member. agent needs a free dialer seat.
sub_account_accessenum: all or organization_only.

Returns data.id. Their email can’t be changed with an API key.

Errors

HTTP	Code	When
400	`invalid_request`, `unknown_field`	Nothing to change, a `role` not in the list, or a field it doesn’t accept.
403	`permission_grant_exceeds_your_own`	The change gives them more access than the key’s user has. Nothing changed.
403	`cannot_edit_own_access`	The key’s user is changing their own role or access.
403	`forbidden`	No dialer seat free for `agent` (other changes you sent were saved).
403	`permission_denied`	The key’s user can’t manage the team.
404	`member_not_found`	No one on this team has that id.
500	`internal_error`	Some changes may have saved. List the team before you send it again.

curl -X PUT "https://api.tryready.com/v1/team-members/5120" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "member"
  }'

const res = await fetch('https://api.tryready.com/v1/team-members/5120', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "role": "member"
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/v1/team-members/5120",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "role": "member"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": { "id": 5120 }
}

#Resend a team invite

Emails a new invite with a new sign-in link. Links in earlier invites stop working. Send an Idempotency-Key header so a retry doesn’t send a second email. Needs the Manage team permission (invite_team).

Parameters

idinteger · pathRequired: Their id from List team members.

Returns data.id, data.email and data.expires_at (when the new link stops working).

Errors

HTTP	Code	When
400	`invalid_request`, `unknown_field`	`id` isn’t a whole number, or the body has a field.
404	`member_not_found`	No one on this team has that id.
403	`permission_denied`	The key’s user can’t manage the team.
500	`internal_error`	The new link could not be made. Send it again.
502	`internal_error`	The new link was made but the email did not go out, and links in earlier invites no longer work. Send it again.

curl -X POST "https://api.tryready.com/v1/team-members/5120/resend-invite" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

const res = await fetch('https://api.tryready.com/v1/team-members/5120/resend-invite', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/team-members/5120/resend-invite",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={

    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": { "id": 5120, "email": "frontdesk@brightsmile.example.com", "expires_at": "2026-11-18T18:20:11.004Z" }
}