Which rules apply to API calls?
| Rule | What happens |
|---|---|
| Own number | The employee calls from its own number. Without one the call is failed with “number required”. |
| Calling hours | Calls 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-call | A number on your list is never dialled: the call is blocked. |
| Cooldown | The same number is not called again within 30 minutes, from any source: the call is blocked. |
| Coins | No coins, no call. Calls use coins at your usual rate; connected time only. |
| Daily cap | 1,000 API calls per workspace per 24 hours (100 before your first payment). Ask us to raise it. |
| Paused employee | The 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?
| status | Meaning | Final? |
|---|---|---|
queued | Waiting its turn; dials within seconds. | No |
scheduled | Waiting for its time, calling hours or the next retry; next_attempt_at says when. | No |
in_progress | Ringing or in conversation. | No |
completed | The person was reached; result has the conversation. | Yes |
not_connected | Every attempt went unanswered, busy or failed. | Yes |
blocked | Stopped by a rule: do-not-call, the 30-minute cooldown or the daily cap. | Yes |
failed | Could not be placed, e.g. the employee has no number. status_detail says why. | Yes |
canceled | You cancelled it while it waited. | Yes |
How do I get the result?
- Pushed: subscribe a webhook to
call.completedandcall.not_connected. Best for automations. - Pulled:
GET /calls/{id}until the status is final (no faster than every 15 seconds), orGET /leads?updated_after=for every result. POST /calls/{id}/cancelstops a call that is stillscheduled.
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.