Skip to main content
POST
Place a Call Endpoint
This endpoint is in beta. The interface is stable enough to build on; we may add fields as it matures.

Overview

Place an outbound call programmatically with a single request. Tuco rings your agent first, then dials the lead from your Tuco number, and bridges the two legs — so the lead sees the same number they’ve been texting, and your rep’s personal number is never exposed.
US and Canada (+1) numbers only.

What you’ll need

Three things before you make a request:
1

Your API key

A workspace API key (starts with tuco_). Get it in the Tuco dashboard under Settings → Integrations → API Keys → Create API Key. Send it as a bearer token: Authorization: Bearer tuco_.... This is the same key used for the Messages API.
2

A voice-verified calling line

The call goes out from a line in your workspace whose caller ID is voice-verified — that’s the number the recipient sees. Pass it as from, using either:
  • the line’s +1 number — simplest, no lookup needed, or
  • the line ID — go to the Lines page in the dashboard; each line row has a Copy Line ID button (the copy icon next to the line) — click it to copy the ID. You can also get it from the List Lines API (each line’s _id).
If the line isn’t voice-verified yet, verify it in the dashboard (or ask your Tuco contact to enable voice on it).
3

Two phone numbers

The lead you want to reach (to) and your rep’s phone (agent), both in E.164 format (US/CA, e.g. +13025550123).

How it works

The lead is only dialed after your agent answers, so a lead is never left listening to dead air.

Making a request

  • Method: POST
  • URL: https://app.tuco.ai/api/voice/calls
  • Headers: Authorization: Bearer tuco_... and Content-Type: application/json
  • Body: JSON with from, to, and agent

Request body

string
required
Your calling line — pass either the line ID or the line’s +1 number. Must be a line in your workspace with a voice-verified caller ID. This is the number the lead sees.
string
required
The number to call, E.164 US/CA (e.g. +13025550123). Non-toll-free. This is just a phone number — the contact does not need to exist in Tuco first; you can call any US/CA number directly.
string
required
Your rep’s phone number, E.164 US/CA. This leg is dialed first — your rep answers, then the number is dialed and bridged in.
string
Optional, advanced. Only if you already have a lead record in Tuco and want the call logged against it (shows in that lead’s Unibox thread). Not required to place a call.

Example


Response

202 Accepted — the call was accepted and is being placed. Ringing takes a few seconds, so the response returns a call ID immediately and the call then progresses asynchronously.
string
The call record ID (MongoDB ObjectId).
string
Always "requested" on a successful create.

Call lifecycle

The call advances through these states on the call record:
Every call is recorded; the recording URL is attached to the call record once the call ends.
The agent leg rings first — your rep must answer within ~30 seconds or the call times out. If the agent’s phone goes to voicemail, the call ends without dialing or bridging the lead.

Getting the recording

Recordings are captured automatically. After a call ends, fetch the recording (and the call’s timing details) with the Get Call Recordings endpoint, using the lead’s number. To get the most recent call’s recording for a lead, pass latest=true:
The recordingUrl in the response is the download link. Drop latest=true to get all calls to that number (newest first).
Recordings resolve a few seconds after the call ends. If you request right on hangup and recordingUrl comes back null, wait ~5-10 seconds and retry. See the Get Call Recordings endpoint for all parameters.

Errors

All errors return { "error": "...", "code": "..." }.