Skip to main content
The dialer lets a salesperson work through a call list from the browser, one contact after the next. This API covers everything around that: an agent or script can configure the dialer, build call lists (they are saved views of the Contacts table), write the call scripts a rep reads on a call, read sessions, calls, transcripts, AI feedback, outcomes and statistics, set outcomes and notes on finished calls, and manage the do-not-call list. The same endpoints power the dialer tools of the MCP server.
The API never places a call, buys a number or changes billing. There is no endpoint to start a dialing session, dial a number, obtain a calling token, buy or release a phone number, or accept the Dialer terms, and no scope grants one. Those actions exist only inside the dashboard for a signed-in person (billing changes: an admin in Settings → Dialer). An agent prepares the list, assigns numbers and reads the results and the costs; a person makes the calls. Settings can still change what those calls cost: a dialer:write credential can turn transcribe_calls on, which bills every transcribed minute of later calls (pricing), and ai_call_feedback, which uses one AI credit per call.

​
Scopes

Changing caller_id, assigning or labelling phone numbers, deleting a call’s recording and transcript, and removing numbers from the do-not-call list additionally need a credential whose owner is a team admin (403 forbidden otherwise). The CRM agent API key preset in Settings → API keys includes both dialer scopes.

​
Endpoints

​
Settings

Defaults apply until a team saves its own. caller_id is the workspace’s default outbound number; it must be one of the numbers the workspace owns. caller_id and require_call_outcome are the settings a non-admin credential cannot change. The transcript settings form a chain: transcribe_calls needs both record_calls and machine_detection on (answering-machine detection is what keeps voicemail out of transcripts), and ai_call_feedback needs transcribe_calls on. A patch that breaks the chain is rejected with 400 invalid_request and a message naming the fix; turning a parent off never silently turns its dependents off, so send them together: { "record_calls": false, "transcribe_calls": false, "ai_call_feedback": false } to stop recording, or { "machine_detection": false, "transcribe_calls": false, "ai_call_feedback": false } to stop detecting answering machines. The reverse holds too: { "transcribe_calls": true, "machine_detection": true } turns transcription on where detection was off.

​
Outcomes

Every finished call carries one outcome. The system sets the automatic ones from how the call ended; a person (or PATCH /api/v1/dialer/calls/:id) picks a manual one after a conversation. reached outcomes count toward the reach rate in statistics. Each workspace starts with the fourteen built-in outcomes below. In Settings → Dialer an admin can rename the manual ones, give them descriptions, hide them, change their order and add the workspace’s own. Keys never change: a renamed outcome keeps its key, and a custom one gets a custom_ key generated from its first name (Left with gatekeeper → custom_left_with_gatekeeper) that stays the same through every rename, so calls, the call.completed webhook, statistics and filters keep matching. Outcomes are hidden rather than deleted: calls that already have one keep it, but it can no longer be set (400 outcome_hidden). connected and do_not_call are always available. Each custom outcome says whether it counts as reaching the contact (reached), which the reach rate in statistics uses. An admin can also require an outcome after every conversation (require_call_outcome). GET /api/v1/dialer/outcomes (MCP: list_call_outcomes) returns the workspace’s list:
The built-in outcomes:

​
Phone numbers and pricing

The Dialer is part of every plan; there is no flat fee. A workspace needs a phone number to call from: an admin buys numbers in Settings → Dialer (also reachable from Billing), and Orbit’s platform phone account buys each one on the workspace’s behalf. The first purchase asks the admin to accept the Dialer terms at /dialer-terms. Numbers and outbound minutes are charged on a separate Orbit Dialer subscription next to the workspace’s plan, on the same card; the first number creates it. How billing behaves:
  • Terms with the first number. The first purchase requires an admin to accept the current Dialer terms (version 2026-11-02); the acceptance is recorded before anything is bought. GET /api/v1/dialer/billing reports in terms which version was accepted, by whom and when, and terms.current tells you whether that is still the version in force.
  • One subscription, created on demand. The first number creates the workspace’s Orbit Dialer subscription with the number and the metered minutes on it; later numbers change the quantity. Releasing a number credits the unused part of the month on the next invoice; releasing the last one leaves the subscription with only its metered items, so nothing more is charged until the next purchase.
  • Subscription state. subscription.status is none until the first number, then active. past_due means Stripe is retrying a failed payment; dialing continues meanwhile. canceling (with cancel_at) only happens when support schedules a cancellation; when it takes effect, or when the subscription ends for non-payment, every number the workspace owns is released.
  • Dashboard only. Buying and releasing numbers, and accepting the terms, change what the workspace is charged, so none of them has an API endpoint or MCP tool. The API reads the costs (GET /api/v1/dialer/billing) and the numbers, and can assign and label numbers.
Incoming calls (set per number in Settings → Dialer → Phone numbers, admins):
  • Who it rings. A call to a workspace number rings its assigned rep in the browser, anywhere in Orbit (they answer from the card that slides in). A number nobody is assigned to rings whoever last called that person from it, so a prospect calling back reaches their rep; if nobody did, the workspace admins are notified of a missed call and the first admin gets the call-back task. A rep already on a call is not rung.
  • Who sets it up. Admins configure every number; the rep a number is assigned to can change its ring time, forwarding number and greeting. Callers hear that the call may be recorded before it rings when the workspace records calls (a per-number setting, on by default).
  • Then. After the ring time (5 to 60 seconds) the call goes to the number’s forwarding number, if it has one (a US landline or mobile number, or Canadian with Canada turned on; never premium-rate or shared-cost). Whoever answers there must press 1 to take the call; otherwise it goes on to voicemail with a spoken or recorded greeting. Voicemail messages are recorded like calls and, with transcription on, transcribed.
  • Logged and followed up. Every incoming call is logged on the contact whose phone (or a phone-type custom field) matches the caller, with direction: "inbound". A missed call or a voicemail creates a call-back task for the rep and notifies them (the calls notification topic).
  • Numbers can be moved to Orbit from another carrier (Settings → Dialer → Move numbers to Orbit, admins). Orbit staff handle the transfer; the numbers then appear here, billed like bought ones.
Numbers and reps:
  • One number per rep. An admin assigns each number to a team member; that person’s calls go out on it. A rep can hold one active number at a time (409 conflict otherwise).
  • The default number. Reps without a number of their own use the workspace default, caller_id in the settings. The first number a workspace buys becomes the default; if the default is released, the oldest remaining number is used.
  • Assign and label over the API, buy and release in the dashboard. GET /api/v1/dialer/numbers lists what the workspace owns and who holds what; PATCH /api/v1/dialer/numbers/:id reassigns or relabels. There is no POST or DELETE on this resource; a signed-in admin buys and releases from Settings → Dialer. Releasing a paid number credits the unused part of the month on the next invoice.
  • Costs. GET /api/v1/dialer/billing reports the active numbers by type and their monthly total, the billable minutes so far this calendar month and their cost, the transcribed minutes billed so far this month and their cost (transcript_minutes), the list prices (prices, with transcript_minutes_cents for transcription), feedback (how many calls the AI coach wrote feedback for this month and the AI credits that used, one per call), monthly_total_cents (numbers only; metered usage excluded), the subscription state and the terms acceptance. Unanswered calls bill nothing, and neither does a call that was not transcribed.

​
Call lists are saved views

A call list is nothing more than a saved view of the Contacts table (or a static list of contacts, dialed in the Contacts table’s default order): its filters pick the people, its sort sets the dialing order. Build one with POST /api/v1/contact-views (or create_contact_view over MCP), list existing ones with GET /api/v1/contact-views, then check what it would dial with GET /api/v1/dialer/call-lists/preview?view_id=. The dialer only calls numbers in the United States; the country comes from the number itself, so a +1 number in Jamaica, the Bahamas or Puerto Rico is outside it. The preview applies the dialer settings and reports who is left out and why: A session holds at most 500 dialable contacts (truncated: true when the view has more); the first 2,000 contacts of the view are examined. A person then opens the view on the Dialer page and starts dialing. The API does not start sessions; it can only read them afterwards.

​
Call scripts

A call script is the text a rep reads during a call. The Dialer page shows it beside the call with the merge fields filled in from the contact being dialed, and highlights the ones it could not fill. Scripts belong to the team; one can be the default, which new sessions start with unless the person picks another when they set up the session (the session’s script_id records which one). Merge fields: {{first_name}}, {{last_name}}, {{full_name}}, {{company}}, {{job_title}}, {{email}}, {{phone}} from the contact, and {{rep_name}} for the person calling.
Scripts are read by a person on a call; nothing about them places one. The AI coach is given the session’s script, rendered for the contact, so it can judge how closely the conversation followed it.

​
Playbooks

In the app, scripts are managed as playbooks (Settings → Playbooks): a call script, a battle card or a list of discovery questions. A playbook with show_on appears as a Playbooks tab on contact and/or deal pages, its merge fields filled from the contact (on a deal, its primary contact), and its contact questions are also answered in the Dialer beside the call. A question’s field is one of the object’s custom fields (GET /api/v1/crm/fields) or one of these built-in columns: first_name, last_name, job_title, company, phone on contacts; name, amount, close_date, description on deals. Each field takes one question per playbook, and a field that doesn’t exist is a 400. Answers are saved by people from the record page or the Dialer, under the same rules as any edit there: record access, the field’s type and validation rules (422 with errors[]), and the pipeline’s rules. To write those fields from code, update the contact or deal directly.

​
Transcripts and AI feedback

With transcribe_calls on, every recorded conversation (a call a person answered; voicemail and unanswered calls are skipped) is transcribed once it ends, and with ai_call_feedback on the AI coach then writes feedback for the rep. Both land on GET /api/v1/dialer/calls/:id/insights, one record per call; the call itself carries an insights summary with the two statuses so a list can show what is ready. Transcription happens in the background: poll while a status is queued or processing. feedback has this shape:
score is 1–10 or null when the call was too short to judge; script_adherence.followed is yes, partly, no or no_script; suggested_outcome is one of the outcomes for the rep to compare with what they picked. The whole record is read-only over the API: the background job writes it.

​
Deleting recordings

DELETE /api/v1/dialer/calls/:id/recording (or delete_call_recording over MCP) removes a call’s media: the audio recording is deleted at the carrier, and the transcript, its sentences and the AI feedback are deleted at the transcription service and from Orbit. The call itself stays, with its numbers, timings, duration_seconds, outcome and notes, so statistics and the contact’s call history are unchanged; its recording_status becomes absent, its insights summary null, and GET /api/v1/dialer/calls/:id/insights answers 404 not_found from then on. The deletion is recorded in the workspace’s audit log and cannot be undone. Admins only (403 forbidden otherwise); 409 conflict when the call has neither a recording nor a transcript. Deleting a contact also deletes the media of every call made to them, but the two ways of deleting differ when a provider fails. In the dashboard the contact is kept until every call’s media is gone, so the delete can simply be retried. DELETE /api/v1/contacts/:id purges best effort: if the carrier or transcription service fails for a call, the contact is still deleted and that call keeps its recording or transcript, now with contact_id: null. Find such calls with GET /api/v1/dialer/calls and remove their media with this endpoint.

​
Do-not-call list

The list is keyed by phone number, stored in E.164 and matched by digits, so +1 (555) 010-0100 and 5550100100 are the same entry. Numbers in any format are normalised with the team’s default_country; the response separates added, already_listed and invalid.
  • Contacts carrying a listed number are flagged do_not_call and skipped by every call list; the pre-dial check blocks them even if a list was built earlier.
  • Email unsubscribes and SMS opt-outs add the contact’s number automatically (reason: email_unsubscribe, sms_opt_out). The outcome do_not_call on a call adds it with reason: call_outcome.
  • Removing a number from this list does not remove the email unsubscribe or SMS opt-out behind it, and the next unsubscribe adds it back.
  • Only admins remove numbers; any credential with dialer:write can add them.

​
Responses

Lists return { "data": [...], "meta": { "total", "page", "per_page", "total_pages" } }; single records return { "data": {...} }. Errors return { "error", "error_description" } with a 4xx or 5xx status, for example 403 forbidden when a non-admin changes caller_id, assigns a number or removes a do-not-call entry, 409 conflict when assigning a number to someone who already holds one or when two callers make different scripts the default at once, 404 not_found for a call that has no insights yet, and 503 unavailable when calling is not configured on the instance.

MCP tools

The same operations as MCP tools

CRM API

Saved contact views and the rest of the CRM