What happens after I place a call through the API?

A call placed through the API joins the same queue as a lead from your website and follows every rule the dashboard follows. The API adds no way around them.

Which rules apply to API calls?

RuleWhat happens
Own numberThe employee calls from its own number. Without one the call is failed with “number required”.
Calling hoursCalls are placed between 9 AM and 9 PM India time. Outside them the call is scheduled for the morning (requests older than 36 hours are not called).
Do-not-callA number on your list is never dialled: the call is blocked.
CooldownThe same number is not called again within 30 minutes, from any source: the call is blocked.
CoinsNo coins, no call. Calls use coins at your usual rate; connected time only.
Daily cap1,000 API calls per workspace per 24 hours (100 before your first payment). Ask us to raise it.
Paused employeeThe call is failed (employee paused). Switch the employee back on and place it again.

How do I schedule a call for later?

Send scheduled_at (a UTC time, up to 30 days ahead) on POST /calls. The call waits as scheduled with next_attempt_at set; a time outside 9 AM to 9 PM India time moves to the next opening, and the answer shows the time it will really ring. Cancel with POST /calls/{id}/cancel any time before it rings.

Instead of phone you can send contact_id (a contact: the call uses their contact fields) or lead_id (call a lead again: the new attempt and its result stay on the same lead). Calls your team places from the dashboard appear in GET /calls with source: "dashboard".

How do automatic retries work?

Set max_attempts (1 to 3) and retry_after_minutes (15 to 1,440) on POST /calls. When a call is not answered, is busy or fails, it is tried again after the gap, inside calling hours. After the last attempt the call ends as not_connected and the call.not_connected event is sent. Unanswered attempts cost nothing.

Campaigns have their own retry settings: max_attempts and retry_after_minutes on POST /campaigns.

When a person asks to be called back (“call me at 5 pm”), the lead's callback_at holds that time. With automatic call-backs on (Settings, or one click on Leads & outcomes), the employee calls them then, tries up to 3 times, and chooses a time when they gave none; these calls appear in GET /calls with source: "callback".

What does each call status mean?

statusMeaningFinal?
queuedWaiting its turn; dials within seconds.No
scheduledWaiting for its time, calling hours or the next retry; next_attempt_at says when.No
in_progressRinging or in conversation.No
completedThe person was reached; result has the conversation.Yes
not_connectedEvery attempt went unanswered, busy or failed.Yes
blockedStopped by a rule: do-not-call, the 30-minute cooldown or the daily cap.Yes
failedCould not be placed, e.g. the employee has no number. status_detail says why.Yes
canceledYou cancelled it while it waited.Yes

How do I get the result?

  • Pushed: subscribe a webhook to call.completed and call.not_connected. Best for automations.
  • Pulled: GET /calls/{id} until the status is final (no faster than every 15 seconds), or GET /leads?updated_after= for every result.
  • POST /calls/{id}/cancel stops a call that is still scheduled.

How do placeholders and metadata differ?

details fill the employee's {{placeholders}}, so the AI can say “your MBA enquiry from Pune”. metadata and external_id are only for you: they come back with every result and are never read by the AI. GET /employees lists the placeholders each employee uses.

Ready to try it? Sign in and open Developers to create a key, or ask us about your integration.

Start freeBook a demo