Place a Call Endpoint
Voice / Calling
Place a Call Endpoint
Place an outbound click-to-call from your own system: Tuco dials your agent, dials the lead from your Tuco number, and bridges the two.
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
+1number — 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).
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
Making a request
- Method:
POST - URL:
https://app.tuco.ai/api/voice/calls - Headers:
Authorization: Bearer tuco_...andContent-Type: application/json - Body: JSON with
from,to, andagent
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, passlatest=true:
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": "..." }.