How to Launch Outbound Campaigns Using API Triggers
This guide explains how to enable individual outbound calls via the API, allowing you to initiate a call when an event occurs in your system.
Written By Product
Last updated 3 months ago
Overview
Unlike batch campaigns, where you upload a list and trigger all calls at once, API triggers allow you to initiate a single call in real time. When an event occurs in your system (new lead, completed order, appointment created), your application calls the API at DeepAgent, and the agent immediately calls the contact.
This guide covers the most common use case. The complete and up-to-date reference for all endpoints is available in the DeepAgent API Documentation.
Typical Use Cases
Real-time leads: A potential customer fills out a form on the website, and the agent calls them within 30 seconds to qualify them.
Order confirmation: A customer completes a purchase; the agent calls to confirm the details and suggest upsells.
Appointment reminder: 24 hours before an appointment, the management system triggers a confirmation call.
Alerts and notifications: A monitoring system detects an issue; the agent calls the manager to notify them.
Prerequisites
To use API triggers, you must have:
A configured and active outbound agent
A phone number assigned to the agent
An API key DeepAgent with the scope
calls:write(generate it from Settings > API)
API Endpoint
The endpoint to initiate an outbound call is:
POST https://platform.deepagent.app/api/v1/callsRequired headers
Authorization: Bearer da_<env>_<key_id>_<secret>Content-Type: application/jsonIdempotency-Key: <stringa univoca per ogni richiesta>Idempotency-Key is required. It prevents a retry after a timeout from causing a customer’s phone to ring twice: the same key and the same body return the original response, while the same key with a different body returns a 409 response. Use a UUID generated by your system.
There is also an optional `X-Workspace-Id` header to specify the workspace to operate on. Omit it if the key has only one workspace; it is allowed only for keys with partner delegation.
Request Body
{ "agent_id": "6f1c9a24-8b3d-4f7a-9c25-1d0e7a3b5c88", "to": "+393331234567", "variables": { "nome": "Mario", "cognome": "Rossi", "prodotto": "Piano Premium", "scadenza": "28/02/2026" } }agent_id (required): the UUID of the agent who is to make the call. The agent must be active and have an assigned number; otherwise, the call will not go through. You can find this on the agent’s details page.
to (required): the number to call in E.164 format, including the + and the international prefix. If the number is on the exclusion list, the call is rejected.
variables: the dynamic variables the agent will use during the call. They must correspond to the placeholders in the agent’s prompt, and the values must be strings: numbers and Booleans must be converted before being sent.
phone_number_id (optional): the calling number. If omitted, the number assigned to the agent is used.
skip_time_check (optional, default false): skips the time window configured for the agent. Leaving it set to false prevents calls outside of business hours, which is a compliance issue rather than a matter of courtesy.
Response
If successful, you’ll receive a “202 Accepted”:
{ "data": { "id": "9d84a1f0-52c7-4a1e-9f33-0b6e2c7d4411", "status": "queued", "agent_id": "6f1c9a24-8b3d-4f7a-9c25-1d0e7a3b5c88", "phone_number_id": "b27f5e13-90aa-4c6d-8e21-77c4d9f0a562" } }The response arrives before the phone rings: the status is always “queued.” Use “data.id” with “GET /v1/calls/{id}” to track the call’s outcome.
Common Integrations
From a web form
When a user fills out a contact form, your backend can immediately initiate a call:
// Esempio Node.js app.post('/contact-form', async (req, res) => { const { nome, telefono, interesse } = req.body; await fetch('https://platform.deepagent.app/api/v1/calls', { method: 'POST', headers: { 'Authorization': 'Bearer ' + process.env.DEEPAGENT_API_KEY, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() }, body: JSON.stringify({ agent_id: '6f1c9a24-8b3d-4f7a-9c25-1d0e7a3b5c88', to: telefono, variables: { nome, interesse } }) }); res.json({ message: 'Ti richiamiamo subito!' }); });From n8n
Create an n8n workflow with an HTTP Request node that calls the API DeepAgent. You can trigger the workflow from any event: a new Airtable record, a new WooCommerce order, or a new Zendesk ticket.
HTTP Request node configuration:
Method: POST
URL:
https://platform.deepagent.app/api/v1/callsAuthentication: Bearer Token
Additional Header:
Idempotency-Key, populated with the ID of the record that triggered the workflowBody: JSON with
agent_id,to, andvariablesmapped from the previous nodes
From Zapier / Make
Use the "Webhook" action to call the DeepAgent API when a trigger occurs in another app.
From CRM (HubSpot, Salesforce, Pipedrive)
Set up a workflow in your CRM so that when a lead enters a specific stage, it triggers a webhook. The webhook can be your own endpoint that then calls the DeepAgent API, or you can use n8n/Zapier as an intermediary.
Callback Webhook
You can receive a notification when the call ends by subscribing to a webhook. The available events are call.completed, call.failed, campaign.completed, recall.scheduled, message.received, and contact.created.
The destination endpoint must be in https, because the payload contains your customers’ data. When you create a subscription, you receive a secret, which is displayed only once: it’s used to verify the X-DeepAgent-Signature signature of each delivery, in the format t=<epoch>,v1=<hmac-sha256 di "<t>.<body>">. Always verify the signature before processing the content: without that check, your endpoint will accept any POST request coming from the Internet.
The exact structure of each event’s payload is described in the API documentation. With this data, you can update your CRM, notify the sales team, or trigger other automations based on the outcome.
Managing Queues and Rate Limits
The API is subject to rate limits: if you exceed them, you’ll receive a “429 Too Many Requests.” Implement a retry with exponential backoff, reusing the same Idempotency Key from the original request, so that a retry does not generate a second call.
Calls are queued and processed in order. If the agent is already handling a call, new calls will wait until the agent becomes available: keep this in mind if you initiate many calls in a short period of time.
Handling Errors
Every error returns an `error` object containing `code` (the stable code on which to base your logic), `message` (in English; this may change between versions—do not compare it in your code), `details`, and `request_id`. Always include the `request_id` when reporting an issue to support—this is what allows them to locate the request in the logs.
400 Bad Request: missing parameters or incorrect format. Check agent_id and the E.164 format at to.
401 Unauthorized: Missing, invalid, or revoked API key.
403 Forbidden: The key does not have the calls:write scope, or it is not authorized for the requested workspace.
409 Conflict: You reused a Idempotency-Key with a different body.
429 Too Many Requests: Rate limit exceeded; please try again with backoff.
500 Internal Server Error: DeepAgent-side issue; please try again or contact support via request_id.
Monitoring
All calls initiated via the API appear in the Call History. You can filter them to see only those triggered programmatically.
Via the API, GET /v1/calls/{id} returns details for a single call, while GET /v1/calls/{id}/transcript and GET /v1/calls/{id}/recording provide transcripts and recordings. Use this data to analyze performance and optimize agent operations.
Best Practices
Validate the number first: verify that it is in E.164 format before calling the API. Malformed numbers consume a request without actually placing the call.
Generate a deterministic idempotency key: by using the ID of the source record (lead, order, appointment), you can prevent duplicate calls even if your system retries.
Respect consent: Initiate calls only to numbers that have given consent, and keep track of consent in your system.
Limit automatic retries: if a number does not answer, do not retry immediately. Use backoff logic or schedule a manual retry.
Log everything: Save API responses, including the request_id, for debugging and auditing.
Test first: Before connecting the API to the production system, test with test numbers to verify that everything works.