Calls

Start a call from your own app with click-to-call: we ring your team member, then connect them to the lead. Each call has its outcome, plus the recording and transcript when recording was on. A key for a team member who only sees assigned leads only gets their calls and calls with their leads.

Calling uses the texting permissions: reading calls needs view_messages, and starting a call, hanging up and setting an outcome need send_sms. There is no separate calling permission, so a key that can’t text can’t call. The outcome your team logs is the disposition field. The outcome field is the call result Ready records (answered, voicemail, no_answer, busy, failed or missed); logging a disposition doesn’t change it, and filtering List calls by outcome takes only those results.

An agency can read the calls of all its sub-accounts in one list with sub_account. Your account’s call settings (recording, who rings for incoming calls) are under Call settings.

#The Call object

Get a call and List calls both return this object, transcript included.

call_idstring: out_ for a call you or the Ready Dialer started (for example out_123), in_ for a call to one of your numbers (for example in_456), ft_ for a FaceTime Audio call either way (for example ft_789). Each prefix has its own numbers, so out_12 and ft_12 are two different calls.
channelenum: phone or facetime. A facetime call is a FaceTime Audio call placed or answered in the Ready Dialer (its audio runs in the browser); it sends the same call webhooks as a phone call.
directionenum: outbound or inbound.
fromE.164 string: Who called.
toE.164 string: Who was called.
statusstring: The call’s state. Right after Start a call the response says ringing_agent. Get a call says agent_ringing while your team member’s phone rings, bridging while we connect the lead, then ringing, connected, completed or failed. A FaceTime call that has ended is completed or failed.
outcomeenum: The call result Ready recorded: answered, voicemail, no_answer, busy, failed or missed. An outbound call that reached voicemail or a call screener is never answered.
duration_secondsinteger: Talk time.
dispositionstring | null: What the agent logged after a Ready Dialer call.
notesstring | null: Notes the agent logged after a Ready Dialer call.
contact_idinteger | null: The contact on the call, when we know them.
contact_namestring | null: That contact’s name.
agent_idinteger | null: The team member who placed or answered it.
agent_namestring | null: That team member’s name.
recording_urlstring | null: The recording, fetched with the same API key. null when the call wasn’t recorded. A FaceTime call has one when the Ready Dialer recorded it.
transcriptstring | null: null until it’s ready, and always null when the call wasn’t recorded. FaceTime calls have no transcript. Always in English: a call in another language is translated.
created_atISO 8601 string: When the call started.
sub_account_idinteger: Only in a list read with sub_account from your main account: the account the call is on. Your main account’s own calls carry its id.
sub_account_namestring | null: Only with sub_account_id: that account’s name. Its recording_url ends in ?sub_account= and the id, so it opens with your key.

#List calls

Newest first, phone and FaceTime calls together, once each call has ended. Page through with next_cursor. Needs the view_messages permission. Returns a list of Call objects in data, each with its transcript.

Parameters

directionenum, query: outbound or inbound. Leave blank for both.
channelenum, query: phone or facetime. Leave blank for both.
outcomeenum, query: answered, voicemail, no_answer, busy, failed or missed.
sinceISO 8601 string, query: Only calls from this time on, for example 2026-10-01 or 2026-10-01T00:00:00Z. A date or time without an offset is UTC, so a bare date is that UTC day; send an offset (2026-10-01T00:00:00-05:00) for your own day.
untilISO 8601 string, query: Only calls up to this time. Give a date like 2026-10-31 and that whole UTC day is included. An impossible date such as 2026-02-30 is refused with 400 invalid_field.
searchstring, query: A phone number or a contact’s name.
contact_idinteger, query: Only calls with this contact: the contact’s call history.
sub_accountstring, query: all for the calls of your main account and every sub-account in one list, or one account’s id for that account alone. Each call then has sub_account_id and sub_account_name. Needs a key for the main account’s owner or an admin there. A key for a sub-account gets only its own calls, without those two fields.
limitinteger, queryDefault 25Max 999: Calls per page. A value that is not a whole number up to 999 is refused with 400 invalid_field.
cursorstring, query: The next_cursor from the last page.

Returns

has_moreboolean: Whether there’s another page.
next_cursorstring | null: Pass it as cursor for the next page.

Errors

HTTP	Code	When
400	`invalid_cursor`	The cursor is out of date. Start again without one.
403	`conversation_not_allocated`	With `contact_id`: the key’s user is limited to some of your numbers, and this contact’s conversation is on another one.
403	`sub_account_scope_forbidden`	With `sub_account`: the key is not for the main account’s owner or an admin there, or its user only sees assigned leads.
403	`organization_only`	With `sub_account`: the key’s user has Organization only access.
404	`sub_account_not_found`	The `sub_account` id is not one of your accounts.
422	`too_many_sub_accounts`	`sub_account=all` with too many sub-accounts for one list. Ask for one at a time.

curl "https://api.tryready.com/v1/calls?direction=inbound&outcome=missed&limit=25" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/calls?direction=inbound&outcome=missed&limit=25', {
  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/calls?direction=inbound&outcome=missed&limit=25",
    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}')

#Get a call

One call, with its transcript. Needs the view_messages permission. Returns a Call object in data.

Parameters

idstring, pathRequired: out_123, in_456 or ft_789.
sub_accountstring, query: For a call on one of your sub-accounts: all, or that account’s id. Same rules as List calls.

Errors

HTTP	Code	When
403	`sub_account_scope_forbidden`	With `sub_account`: the key may not read across sub-accounts.
404	`call_not_found`	No call with this id on your account, or on the accounts `sub_account` names.

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

const res = await fetch('https://api.tryready.com/v1/calls/out_123', {
  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/calls/out_123",
    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}')

#Get a recording

The audio file itself. Range requests work, so you can stream it. Needs the view_messages permission.

Parameters

idstring, pathRequired: out_123, in_456 or ft_789. A FaceTime recording is WebM or Ogg audio.
sub_accountstring, query: For a call on one of your sub-accounts. The recording_url of a list read with sub_account already has it.

Errors

HTTP	Code	When
403	`sub_account_scope_forbidden`	With `sub_account`: the key may not read across sub-accounts.
404	`recording_not_found`	The call wasn’t recorded, or the recording isn’t stored yet. Try again in a few minutes.

curl "https://api.tryready.com/v1/calls/out_123/recording" \
  -H "X-API-Key: $READY_API_KEY" \
  -o call.mp3

import { writeFile } from 'node:fs/promises';

const res = await fetch('https://api.tryready.com/v1/calls/out_123/recording', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
await writeFile('call.mp3', Buffer.from(await res.arrayBuffer()));

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/calls/out_123/recording",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
with open("call.mp3", "wb") as f:
    f.write(r.content)

#Start a call

Click-to-call. We ring your team member’s phone first, and when they pick up we dial the lead and connect them. The lead sees your Ready number, same as a Ready Dialer call. Billed at your Ready Dialer rate (see Billing) for each minute the lead is on the line, rounded up to the next whole minute; a call the lead doesn’t answer is free. Needs the send_sms permission.

When recording is on

When Record calls is on for your account, the call is recorded like a Ready Dialer call: when the lead answers, the lead and your team member both hear the recording notice first, and the call is kept only if the notice played to the end. If you signed the notice waiver, it’s recorded from the answer with no notice. Recording is free; get it with Get a recording.

Parameters

Idempotency-Keystring, headerRecommended: Send one so a retried request never rings anyone twice (Idempotency).
toE.164 stringRequired: The lead. US, Canadian, UK or Australian numbers.
agent_phoneE.164 string: The phone we ring first, usually your team member’s cell. Same country as the number we call from. Leave it out to ring the verified phone on your profile.
from_number_idinteger: Call from this number (an id from your numbers). Leave it out and we pick one, preferring a local area code.

Returns

data.call_idstring: Use it with Get a call, hang up and outcome. The call webhooks carry it too.
data.statusstring: ringing_agent: your team member’s phone is ringing.
data.fromE.164 string: The number the lead will see.

Errors

HTTP	Code	When
400	`bad_to`	`to` isn’t a US, Canadian, UK or Australian number.
400	`bad_agent_phone`	`agent_phone` isn’t a US, Canadian, UK or Australian number, or it was left out and your profile has no verified phone.
402	`insufficient_balance`	Your balance doesn’t cover a minute.
402	`client_card_required`	No card on file. Add one in Billing.
403	`account_held`	Calling is paused on this account.
409	`opted_out`	The lead opted out (a STOP covers calls too).
409	`do_not_call`	The contact is marked do not call.
409	`state_call_cap`	A 4th call in 24 hours to a lead in FL, MD or OK.
409	`blocklisted`	The lead’s number is on Ready’s block list.
409	`au_dncr`	The lead’s Australian number is on Australia’s Do Not Call Register.
409	`quiet_hours`	It is outside your sending hours (Settings, Compliance, Sending windows) where the lead is (a lead who texted you in the last 24 hours can be called back).
409	`agent_opted_out`, `agent_do_not_call`, `agent_blocklisted`	`agent_phone` opted out, is marked do not call, or is on Ready’s block list.
409	`no_calling_number`	No number on the account can call that country.
409	`bad_from`	`from_number_id` isn’t one of your numbers that can call.
409	`wrong_country`	The phones are in different countries from the calling number.
429	`too_many_live_calls`	This team member already has the most calls open at once.
502	`provider_failed`	The call couldn’t be placed. Nothing was charged.
503	`spend_check_failed`	We couldn’t check your balance, so no call was placed. Try again in a moment.
500	`internal_error`	The call may have started. Retry with the same `Idempotency-Key`, which never rings anyone twice, or wait for the call webhooks.

curl -X POST "https://api.tryready.com/v1/calls" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+12125550199",
    "agent_phone": "+12125550123"
  }'

const res = await fetch('https://api.tryready.com/v1/calls', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": "+12125550199",
    "agent_phone": "+12125550123"
  }),
});
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/calls",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "to": "+12125550199",
        "agent_phone": "+12125550123"
    },
    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": {
    "call_id": "out_9182",
    "status": "ringing_agent",
    "from": "+12125550100"
  }
}

#Hang up a call

Ends a call for both people. Works on Ready Dialer calls too. Needs the send_sms permission.

Parameters

idstring, pathRequired: An out_ id: a call you or the Ready Dialer started. Calls to your numbers (in_) can’t be hung up or given an outcome here.

Returns

data.call_idstring: The call you hung up.
data.endedboolean: false when the call had already ended.

Errors

HTTP	Code	When
404	`call_not_found`	No outbound call with this id on your account.

curl -X POST "https://api.tryready.com/v1/calls/out_9182/hangup" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/calls/out_9182/hangup', {
  method: 'POST',
  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.post(
    "https://api.tryready.com/v1/calls/out_9182/hangup",
    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": {
    "call_id": "out_9182",
    "ended": true
  }
}

#Set a call outcome

Logs how the call went. A new outcome starts your call-outcome automations; sending the same one again does nothing. Needs the send_sms permission.

Parameters

idstring, pathRequired: An out_ id: a call you or the Ready Dialer started. Calls to your numbers (in_) can’t be hung up or given an outcome here.
dispositionenumRequired: interested, callback, not_interested, voicemail, no_answer, wrong_number or dq.

Errors

HTTP	Code	When
400	`invalid_field`	Not one of the outcomes above.
404	`call_not_found`	No outbound call with this id on your account.

curl -X POST "https://api.tryready.com/v1/calls/out_9182/outcome" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "disposition": "interested"
  }'

const res = await fetch('https://api.tryready.com/v1/calls/out_9182/outcome', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "disposition": "interested"
  }),
});
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/calls/out_9182/outcome",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "disposition": "interested"
    },
    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": {
    "call_id": "out_9182",
    "disposition": "interested"
  }
}