Calls

The Calls API places FaceTime audio calls from your lines. It never dials on its own: every outbound call is prepared by the API and started by a person who presses Start call. The MCP calling tools (list_calling_lines, prepare_call, get_call_status, end_call) run on the same resource.

What it covers

List calling lines

GET https://api.bluereacher.com/v1/calling-lines

{
  "object": "list",
  "data": [
    {
      "id": "4b30a74e-34e0-49f7-9df2-ecab5df05e87",
      "object": "calling_line",
      "label": "Line 2",
      "phone_number": "+14155550142",
      "provider": "facetime",
      "readiness": "ready"
    }
  ]
}

readiness is one of ready, offline, busy or not_ready.

Prepare a call

curl -X POST https://api.bluereacher.com/v1/calls \
  -H "Authorization: Bearer brk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-call-48391" \
  -d '{
    "to": "+13035550199",
    "line_id": "4b30a74e-34e0-49f7-9df2-ecab5df05e87",
    "contact_name": "Alex Rivera",
    "client_reference": "crm-48391"
  }'

{
  "id": "54cf78b7-1f0e-4c2a-9b7d-3e8a6c1d2f40",
  "object": "call",
  "provider": "facetime",
  "status": "prepared",
  "to": "+13035550199",
  "line_id": "4b30a74e-34e0-49f7-9df2-ecab5df05e87",
  "client_reference": "crm-48391",
  "confirmation_required": true,
  "confirmation_url": "https://app.bluereacher.com/api/v1/call-session?token=...",
  "confirmation_expires_at": "2026-09-10T17:08:00.000Z",
  "created_at": "2026-09-10T17:03:00.000Z",
  "confirmed_at": null,
  "started_at": null,
  "answered_at": null,
  "completed_at": null,
  "duration_seconds": null,
  "failure_code": null
}

A person signed in to Blue Reacher opens confirmation_url, checks the line and the masked destination, and presses Start call. Nothing dials before that. The session expires after five minutes.

Send an Idempotency-Key on every prepare. A retry with the same key and body returns the original call; a different body answers 409 idempotency_conflict. One live session per line at a time.

Lifecycle

prepared -> confirmed -> connecting -> ringing -> answered -> completed
prepared -> expired        (nobody confirmed within five minutes)
ringing  -> failed         (the call could not be placed)
ringing  -> cancelled      (ended before it was answered)

failure_code is one of recipient_busy, recipient_declined, no_answer, line_unavailable, cancelled, call_not_started or call_failed. Subscribe to the call webhooks to follow it without polling.

Read a call

GET https://api.bluereacher.com/v1/calls?call_id=54cf78b7-1f0e-4c2a-9b7d-3e8a6c1d2f40

Returns the call object above. For an incoming call the object carries direction: "inbound", from, contact_id, a status of ringing, answered, completed or missed, missed_reason, and recording_available. recording_url is returned on this read only, never in a webhook.

List recent incoming calls, newest first:

GET https://api.bluereacher.com/v1/calls?direction=inbound&line_id=...&limit=20

limit runs 1 to 50.

End, cancel or decline

DELETE https://api.bluereacher.com/v1/calls?call_id=54cf78b7-1f0e-4c2a-9b7d-3e8a6c1d2f40

Safe to repeat. A prepared call becomes cancelled, a live call is ended, and a ringing incoming call is declined (call.missed fires with missed_reason: "declined"). A call that already finished returns as it is.

Hand a call to a teammate

curl -X POST "https://api.bluereacher.com/v1/calls/transfer?call_id=54cf78b7-1f0e-4c2a-9b7d-3e8a6c1d2f40" \
  -H "Authorization: Bearer brk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "to_email": "sam@yourcompany.com" }'

Name the teammate with to_email or to_user_id; they must be the workspace owner or an active team member. Their Blue Reacher screen rings for 45 seconds. When they take it they join the live call, the first person drops off, the customer hears nothing change, and call.transferred fires. If they decline or the offer runs out, the first person keeps the call and nothing fires.

Recording and transcripts

GET   https://api.bluereacher.com/v1/call-settings
PATCH https://api.bluereacher.com/v1/call-settings

Two switches for the key's own workspace: recording_enabled and transcription_enabled. There is no workspace parameter, so a key can only change its own workspace. These work on any live key, beta or not; test keys answer 403 live_key_required.

curl -X PATCH https://api.bluereacher.com/v1/call-settings \
  -H "Authorization: Bearer brk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "transcription_enabled": false }'

Recording can always be switched off. It can be switched on only after the call recording notice has been accepted in the app for the workspace; before that the answer is 409 recording_consent_required. With transcripts off, recordings are kept and no transcript or summary is made. When both are on, call.transcribed delivers the transcript, a summary and the recording link about a minute after the call ends.

Rate limits