Make calls from your program
Your program can ask Atendia for the virtual assistant to call someone. For example: “call this customer the day before and remind them of the appointment on 18 November 2026 at 15:00”. Atendia stores the request, calls when its turn comes and, at the end, sends the result to your program.
The API address is https://api.atendia.pt/api/v1. Every request carries the key in the x-api-key header and a JSON body.
Create the key
- In the console, open «Settings» → «API keys» → «New API key». Give it a name and choose the type «Read and calls».
- Only the owner or an admin creates keys. To create a «Read and calls» key, they also need the right to start and cancel calls. The type cannot be changed later.
- Copy the key when the console shows it: it appears only once. Keep it as a secret (in Make and n8n, in a credential) and never put it in your code.
- A «Read only» key only reads. If it asks for or cancels a call, it gets
403with the codeAPI_KEY_CANNOT_CALL. Keys created before these two types are «Read only». - A key cannot create or revoke keys and cannot touch payments. A revoked, disabled or expired key gets
401at once. When you revoke a key with calls still to go, the console asks whether to cancel or keep them. - Each key can make up to 60 requests a minute. Above that, it gets
429with the codeRATE_LIMITEDand theRetry-Afterheader, with the seconds to wait.
The minimal request
The minimal request carries only the agent and the number to call: POST /outbound-calls with agentId and phoneNumber.
{
"agentId": "00000000-0000-4000-8000-000000000000",
"phoneNumber": "+351210000000"
}Atendia checks that the agent and the calling number belong to the key's account and that the destination is allowed. It answers only after the request is stored.
The answer is 201, with the call's id (outboundId) and its status. Keep the outboundId: you use it to read and to cancel the call.
{
"success": true,
"message": "Outbound call requested",
"data": {
"outboundId": "11111111-1111-4111-8111-111111111111",
"status": "SCHEDULED",
"reason": null,
"waitReason": null,
"scheduledAt": "2026-11-17T09:30:00.000Z",
"reference": null,
"origin": { "type": "api_key", "name": "Agenda" }
}
}What the request carries
agentId: the agent that calls. Required.phoneNumber: the number to call, with the country code, for example+351210000000. Required.fromNumber: the Atendia number that calls. Needed only when the agent has more than one number.scheduledAt: the time from which to call, with a time zone. Without it, the call is for now. See «The “from” time».firstMessage: the virtual assistant's first sentence in this call. Without it, the agent's one is used.systemPrompt: extra instructions for this call. They are added to the agent's instructions and apply to this call only.dynamicVariables: the call's variables, as in the console, for example{"data_consulta": "18 November 2026, at 15:00"}. Write dates in full, with the day, the month and the time, never “tomorrow”: the call can leave later than the time you asked for, for example while it waits for the agent's calling hours.reference: your own reference, for example the booking code. See «The reference».notAfter: do not call after this date and time, with a time zone. Optional. See «Do not call after».
The “from” time
scheduledAtis the time from which the call may leave, not the exact time. At that time the call joins its number's queue, and it leaves when a line is free.- The time always carries the time zone, for example
2026-12-01T10:00:00+00:00. In mainland Portugal the offset is+00:00in winter and+01:00in summer. Without one, the request is refused, so “10:00” never leaves at 11:00. - Up to 5 minutes in the past counts as “now”. Older, the request is refused (
400). Up to 90 days ahead is accepted; further, it is refused. - Spread the times. With 50 reminders for 9:00 on a number with one line, the last ones leave well after 9:00. Space them, for example, 3 minutes apart.
Do not call after
notAfteris the request's deadline: no call of this request starts after it. It is optional. Without it, the call waits with no deadline, as before.- It always carries the time zone, like
scheduledAt. In a reminder, put the appointment time. For example, for an appointment on 18 November 2026 at 15:00:"scheduledAt": "2026-11-17T15:00:00+00:00"and"notAfter": "2026-11-18T15:00:00+00:00". - A deadline that has already passed is refused with
400and the codeNOT_AFTER_IN_PAST. A scheduled time equal to or later than the deadline is refused with400and the codeSCHEDULED_AT_AFTER_NOT_AFTER. In neither case is a call created. - If the deadline passes before the call leaves, for example while it waits for the calling hours, a line or credit, the call no longer leaves. Shortly after the deadline, it becomes «Failed» (
FAILED) with the reasondeadline_passed(«Past the deadline»), and your program receives the result with that reason. Between attempts it is different: see «New attempt». - The read and the result carry
notAfter, with the request's deadline, ornullwhen the request has none.notAfterexists only in the request for one call (POST /outbound-calls), not in the list campaign.
The queue
- Every call asked for through the API starts «Scheduled» (
SCHEDULED). When its time comes, it joins the queue of the Atendia number that calls. - The one with the earliest time leaves first; on a tie, the one asked for first. Single calls leave before the calls of a campaign on the same number.
- A waiting call shows why in
waitReason:line(waiting for a line),credit(waiting for credit) orhours(waiting for the calling hours, see «The agent's calling hours»). New reasons may appear: treat one you do not know as “waiting”. WithoutnotAfter, there is no deadline: it waits until it leaves or you cancel it. - Without credit, the call does not fail: it waits. If automatic top-up is on, it is requested as usual. Atendia tries again at intervals that grow up to 30 minutes, so after you add credit the queue can take up to 30 minutes to resume.
- A request without a time, or whose time has come, tries to call at once, without jumping ahead of calls already waiting. So the answer can take up to about 2 minutes. It gives the status at that moment:
IN_PROGRESS(«In progress»),SCHEDULEDwith the wait reason, orFAILEDwith the reason. - In that case, only missing credit (
402) refuses the request. The call becomes «Failed», no result is sent and the request id is free again. If the account is already waiting for credit, the call joins the wait, without a refusal. - Set your program's timeout to 3 minutes or more. If it gives up earlier, send the request again with the same
Idempotency-Key: it gets the current status, without a second call.
The agent's calling hours
- The agent can have calling hours: the days of the week and a start and end time, the same on every day ticked. You set them in the console, in «Outbound rules», on the agent's page. They come turned off.
- With the calling hours off, nothing changes: the call leaves when its turn comes, at any time.
- With the calling hours on, no call asked for through the API starts outside them. The times are in the agent's time zone, and the end time is already outside: from 9:00 to 18:00, the last call starts before 18:00. Public holidays are not left out. A call in progress is not cut off.
- The scheduled time (
scheduledAt) is still a “from” time. If it falls outside the calling hours, the call waits for the next opening. Waiting calls leave in the order they became ready. - While it waits, the call is «Scheduled» (
SCHEDULED), withwaitReasonhours(«Waiting for calling hours»).nextAttemptAtgives the time it leaves: the later ofscheduledAtand the next opening of the calling hours. At that time, it joins the number's queue, like the others. - When the call waits neither for the calling hours nor for a new attempt,
nextAttemptAtisnull. - If the
notAfterdeadline passes while the call waits for the calling hours, it does not leave: it becomes «Failed», with the reasondeadline_passed(between attempts, see «New attempt»). - The calling hours also apply to the agent's campaigns. They do not apply to the console's «Quick call», which calls at once.
Example: a booking made on Monday, 16 November 2026, at 20:00, for an appointment on 18 November 2026 at 15:00. The agent's calling hours are Monday to Friday, 9:00 to 18:00, Lisbon time. The call waits for the opening on Tuesday at 9:00. Only some fields of data:
{
"outboundId": "11111111-1111-4111-8111-111111111111",
"status": "SCHEDULED",
"reason": null,
"waitReason": "hours",
"nextAttemptAt": "2026-11-17T09:00:00.000Z",
"scheduledAt": "2026-11-16T20:00:00.000Z",
"notAfter": "2026-11-18T15:00:00.000Z",
"reference": "marcacao-4821"
}The reference
referenceis your own id, for examplemarcacao-4821. It comes back in every answer, in the read and in the result.- The reference must not carry personal data: no names, phone numbers or email addresses. Use a code from your own system.
- Up to 200 characters. Spaces at the ends are trimmed, and an empty reference counts as no reference. Line breaks and invisible characters are refused.
- To find the calls of a reference, use
GET /outbound-calls?reference=marcacao-4821. The search is exact and only sees your account.
Repeated requests
- Always send the
Idempotency-Keyheader, with one value per call, up to 200 characters. If the network fails and your program sends the request again, Atendia recognises it and does not call twice. - The same id with the same body returns the same call, with
201and its current status. It holds while the call waits or runs, and for 24 hours after it ends. - The same id with a different body, or used before for a campaign, is refused with
409and the codeIDEMPOTENCY_KEY_REUSED. No new call is created. The id holds while the call waits or runs, and for 24 hours after it ends; after that, the same id creates a new call. - A request refused by validation does not use up the id: fix the request and send it again with the same one.
- Without a time, repeating always works within that period, because the body is the same. With a time, repeating more than 5 minutes after that time is refused (
400), because the time has passed. In that case, first look for the call by its reference. If it does not exist, send the request with a new “from” time and a new id. - Without the header, each send counts as a new request.
The result
- At the end, Atendia sends the result to the agent's «Post-call webhook» (tab «Email and webhooks»), as for other calls. Without that address nothing is sent: your program reads the call instead.
- The body carries the usual fields (
callId,agentId,startedAt,endedAt,durationSeconds,direction,callerId,extractedData) plusstatus,reason,outboundId,campaignId,origin,reference,notAfter,callbackScheduledandcallbackOf(see «The callback»),answeredByandmessageLeft(see «Voicemail»),attempt,maxAttempts,nextAttemptAtandendedByDeadline(see «New attempt»). The transcript and the recording address also come, if the agent's webhook asks for them. - It is sent for every final status:
COMPLETED(answered),NOT_ANSWERED(no answer) andFAILED(failed or cancelled). It is sent for every outbound call, also the ones started from the console, except contacts refused when a console campaign is imported. - A call that ends without ever calling, for example cancelled while queued, sends its result about 2 minutes later, with
callId,startedAtandendedAtset tonull. - The same result can arrive twice. It happens when Atendia sends again a delivery your API did not confirm, or when the call log arrives after a result was already sent. Keep what you have handled and ignore the repeat. If two different statuses arrive for the same call, the last one counts.
- Note: cancelling many calls means many deliveries. Each cancelled call sends its own result; when you cancel a campaign, expect one delivery per contact that had not left yet.
- A request for now that is refused in its own answer (no credit or no plan minutes) sends no result: your program already got the refusal.
- Answer
2xxquickly. If a delivery fails, the result is still available when you read the call.
Example result of a call cancelled while queued:
{
"callId": null,
"agentId": "00000000-0000-4000-8000-000000000000",
"startedAt": null,
"endedAt": null,
"durationSeconds": null,
"direction": "outbound",
"callerId": "+351210000000",
"extractedData": [],
"status": "FAILED",
"reason": "cancelled",
"outboundId": "11111111-1111-4111-8111-111111111111",
"campaignId": null,
"origin": { "type": "api_key", "name": "Agenda" },
"reference": "marcacao-4821",
"notAfter": null
}The callback («Call me later»)
- The agent can have the «Call me later» option. You set it in the console, in «Outbound rules», on the agent's page. It comes turned off. When it is on and the person answers and asks to be called later, the agent agrees on the day and time and, once the person confirms, Atendia books a callback. It applies to all the agent's outbound calls, including those started in the console.
- Atendia decides, not the agent. The callback rings the same number, with the same agent, the same caller number, the same variables, the same extra instructions and the same
reference. Your program does not request it and cannot change its data. - The time must be in the future, up to 30 days ahead, within the agent's calling hours if they are on, and before the request's
notAfter, if there is one. There is at most one callback per call and two per request: the request is the original call plus the callbacks that came from it. - The original call ends as answered (
COMPLETED). Its read and its result carrycallbackScheduled, withat, the time from which the callback leaves, andoutboundId, the callback's id. That way you know the request is not closed yet. Without a callback,callbackScheduledisnull. - The callback is a new call: it is «Scheduled» (
SCHEDULED) until the agreed time and then follows the queue, the agent's calling hours and the credit, like the others. It spends credit like the others. At the end, it sends its own result, with the samereferenceand withcallbackOf, the original call'soutboundId. On other calls,callbackOfisnull. - To see all the calls of a request, search by reference (
GET /outbound-calls?reference=...). A callback is always cancelled by its ownoutboundId, under the rules of a single call. This holds too when it came from a campaign contact: the contact cannot be cancelled that way, but the callback can. Cancelling the campaign cancels it too. - If you cancel a call while the conversation is in progress, the cancel is still refused with
400anddetails.status, anddetails.furtherAttempts: falsecomes too: the conversation ends normally, but no callback is booked any more. - When you revoke a key, the booked callbacks count as calls still to leave: they are cancelled with the others or kept. If they are kept, the console says until when they can still leave.
Example: on a call requested on 16 November 2026, the person asked to be called on 18 November 2026 at 15:00, Lisbon time. Some fields of the original call's result:
{
"status": "COMPLETED",
"outboundId": "11111111-1111-4111-8111-111111111111",
"callerId": "+351210000000",
"reference": "marcacao-4830",
"callbackScheduled": {
"at": "2026-11-18T15:00:00.000Z",
"outboundId": "22222222-2222-4222-8222-222222222222"
},
"callbackOf": null
}And some fields of the callback's result, once answered:
{
"status": "COMPLETED",
"outboundId": "22222222-2222-4222-8222-222222222222",
"callerId": "+351210000000",
"reference": "marcacao-4830",
"callbackScheduled": null,
"callbackOf": "11111111-1111-4111-8111-111111111111"
}Voicemail
- The agent recognises when it reaches voicemail or another recording, and does not talk to it. What it does next is chosen in the console, in «Outbound rules», on the agent's page: «End the call, no message» (the default) or «Leave a message». It applies to all the agent's outbound calls, including those started in the console.
- The message is your own text, up to 500 characters, and it can use the call's variables (
dynamicVariables). The agent waits for the recording to end, says the text once, exactly as written, in the agent's voice, and ends the call. If the agent's voice is not ready in time, a backup voice says the exact text, and the message is left. A text without variables is recorded in the agent's voice at the first voicemail and used again for the next ones. Write dates in full in the variables, for example «18 November 2026 at 15:00», never “tomorrow”. - No message is left when a variable is missing or empty and the agent has no fallback value for it, when the filled-in text is longer than 1000 characters, when the recording does not end in time, or when the recording does not take messages (for example, «this number is not assigned»). When a variable is missing, the console's call history says which one.
- The message is recorded on a phone other people may listen to. Do not put the reason for the appointment or any other health data in it, nor in the variables it uses.
- A call answered by voicemail or another recording ends as «No answer» (
NOT_ANSWERED), as when nobody answers, and it uses the seconds it lasted, because the line was answered. The same goes for an answered call where nobody speaks until the end. When in doubt, the agent treats whoever answered as a person. - The read and the result carry
answeredBy, who answered:person(a person),voicemail(voicemail),operator_recording(a network recording, such as «the phone is switched off», or a menu, when the agent does not navigate menus) ornobody_spoke(answered, but nobody spoke until the end). answeredByonly comes when recognition ran, or withnobody_spoke, which always comes. Otherwise, for example when nobody answers or when Atendia suspends recognition, it isnullor missing: treat both the same way.messageLeftsays whether a message was left:trueonly when the agent said it. Treat any other value as “no message”. With «End the call, no message», it is nevertrue.
Example: in a reminder for the appointment on 18 November 2026 at 15:00, voicemail answered and the agent left the message. Some fields of the result:
{
"status": "NOT_ANSWERED",
"outboundId": "33333333-3333-4333-8333-333333333333",
"callerId": "+351210000000",
"durationSeconds": 31,
"reference": "marcacao-4835",
"answeredBy": "voicemail",
"messageLeft": true
}New attempt
- The agent can call again on its own when the call does not reach a person. You switch it on in the console, in «Outbound rules», on the agent's page, in the «New attempt» block. It comes switched off. You choose how many times it calls again, from 1 to 5 (2 when you switch it on), and the interval: 5, 15 or 30 minutes, 1, 2, 4, 8 or 24 hours (1 hour when you switch it on).
- It calls again when nobody answered, the number was busy or rejected the call, voicemail answered and no message was left, another recording answered, or someone answered and nobody spoke. It does not call again when the person answered, when a message was left, when the call failed (
FAILED) or when it was cancelled. - It applies to calls asked for through the API, to list campaigns, to console campaigns and to callbacks. It does not apply to the console's «Quick call».
- The interval counts from the end of the previous attempt. Each attempt waits for the agent's calling hours, for a line and for credit, like any call.
- For your program it is always the same call: the same
outboundId, the samereferenceand one result, sent after the last attempt. Between attempts the call is «Scheduled» (SCHEDULED), withwaitReasonretry(«New attempt»), andnextAttemptAtsays when the next attempt leaves. If that time falls outside the agent's calling hours, it comes withwaitReasonhoursinstead, and the time they open. - The read and the result carry
attempt, the attempt the call is on:1for the first call; while it waits for the second, it is already2. In the result, it is the attempt the call ended on.maxAttemptsis the most calls of the request: 1 plus the agent's new attempts, and never fewer than the attempts already made. Without new attempts, both are1. - With
notAfter, no attempt starts after the deadline. If the deadline passes between attempts, the call ends with the last attempt's status, «No answer» (NOT_ANSWERED), with noreason, and withendedByDeadlineset totrue. In every other case,endedByDeadlineisfalse. - Cancelling the call between attempts cancels the ones left. Switching the option off on the agent does not cancel attempts already booked: if you do not want them, cancel the call. «Revoke and cancel» on a key also cancels the attempts left; «Revoke and keep» lets them go.
- Each new attempt is a call. A call nobody answers uses no credit. A recording that answers and a call answered in silence use the seconds they lasted.
Example: a reminder for an appointment on 18 November 2026 at 15:00. The agent calls again twice, an hour apart. Nobody answered the first call, which ended on 17 November at 10:00, Lisbon time. The read shows the call waiting for the second one:
{
"outboundId": "44444444-4444-4444-8444-444444444444",
"status": "SCHEDULED",
"waitReason": "retry",
"nextAttemptAt": "2026-11-17T11:00:00.000Z",
"attempt": 2,
"maxAttempts": 3,
"endedByDeadline": false,
"notAfter": "2026-11-18T15:00:00.000Z",
"reference": "marcacao-4840"
}Set up the signature
- To know that the result comes from Atendia, create the organization's signing secret, which starts with
whsec_, in the console, in «Settings» → «Request signing». API keys cannot create it. With it, each delivery carrieswebhook-id,webhook-timestampandwebhook-signature. - With a call log, the
webhook-idisatd_postcall_, the agent id,_and thecallId. Without a call log, it isatd_postcall_, the agent id,_, theoutboundId,_and the status in lower case, for example_failed. A repeat of the same delivery carries the samewebhook-id. The result that arrives with the call log, after one sent without it, carries another id: recognise it by the pairoutboundIdandstatus. - Without a signature, recognise a repeated delivery by the pair
outboundIdandstatus.
How to verify the signature, with examples: the HTTP tools page, «Request signing».
Read a call
GET /outbound-calls/{outboundId}returns the call in one request:status,reason,waitReason,nextAttemptAt,scheduledAt,notAfter,callbackScheduled,callbackOf,answeredBy,messageLeft,attempt,maxAttempts,endedByDeadline,reference,origin,durationSecondsand the collected data (extractedData).- A waiting call shows its time and why it waits. While it waits for the calling hours or for a new attempt, it also shows the time it leaves, in
nextAttemptAt. A cancelled call isFAILEDwith the reasoncancelled. - If the agent keeps no personal data,
noDataKeptistrueand the collected data is empty. Shortly after the call ends and its result is out, Atendia also deletes the number, the first sentence, the instructions and the variables. Thereferencestays. - A call of another account answers as if it did not exist (
404), and a search for another account's reference returns an empty list.
The statuses
SCHEDULED: «Scheduled», waiting for its time, waiting for the agent's calling hours, in the queue or waiting for a new attempt.IN_PROGRESS: «In progress».COMPLETED: answered and ended.NOT_ANSWERED: «No answer». Also when voicemail or another recording answered, or when nobody spoke (see «Voicemail»). If the agent has new attempts switched on, Atendia calls again on its own, and this status only comes after the last attempt (see «New attempt»). Without it, your program decides whether to ask for another call.FAILED: «Failed», with the reason inreason. A cancelled call isFAILEDwithreasoncancelled.
Cancel
POST /outbound-calls/{outboundId}/cancelcancels a «Scheduled» call, timed or queued. The answer is the call,FAILEDwith the reasoncancelled, and your program receives the result with that reason.- Cancelling a call that is already cancelled returns the same answer, without a new delivery.
- If the call has already started dialing, or has ended, the cancel is refused with
400, anddetails.statusgives the current status. While the conversation is in progress,details.furtherAttempts: falsecomes too (see «The callback»). - A key cancels only single calls asked for by keys; the calls of a campaign are cancelled with the campaign. Calls started from the console are cancelled in the console; to the key, they answer
404. - If you only have the reference, first look for its calls with
GET /outbound-calls?reference=...and cancel each one by itsoutboundId. - A campaign asked for by a key is cancelled with
POST /outbound-calls/batches/{campaignId}/cancel. Calls already in progress end normally.
Campaign from a list
POST /outbound-calls/batches/listcreates a campaign with the list in the request itself:name,agentId,fromNumber(if the agent has more than one number),scheduledAt(optional, with the time rules) andcontacts.- Each contact carries
phoneNumberand, if you want,firstMessage,systemPrompt,dynamicVariablesandreference. In a campaign, a contact's instructions replace the agent's for that call. Variable names follow the file column rules: lower case, no spaces. - Up to 5,000 contacts and 2 MB per request. Above 2 MB, the answer is
413with the codeREQUEST_TOO_LARGE. Send larger lists as a file. - The answer says how many contacts were accepted (
accepted) and how many were not (rejectedCount), and lists the first 100 refused ones, with the position, the reference and the reason. The others go on. - The campaign shows in «Campaigns» in the console. Each call sends its own result, with the contact's reference. The
Idempotency-Keyheader works as for a call request.
Refusal codes
Every refusal carries the usual error body: success: false, code, message (in English), details, fieldErrors and requestId. Decide by the HTTP status and the code, never by the message.
| Code | HTTP | What it means | What to do |
|---|---|---|---|
API_KEY_CANNOT_CALL | 403 | The key is «Read only». | Create a «Read and calls» key in the console and use it. |
IDEMPOTENCY_KEY_REUSED | 409 | The request id was already used with another body, or for a campaign. | Use a new id for a new request. To find out what happened to the first one, look it up by its reference. |
RATE_LIMITED | 429 | More than 60 requests a minute with this key. | Wait the seconds in Retry-After and try again. |
DESTINATION_RULE_MISSING | 400 | The calling number's carrier has no destination rule, so calls asked for by key cannot leave from that number. | Use another Atendia number in fromNumber, or contact us. |
OUTBOUND_API_PAUSED | 503 | Atendia has paused calls asked for by key, in an emergency. Reading and cancelling still work. | Try again later. Calls already accepted wait and leave when the pause ends. |
REQUEST_TOO_LARGE | 413 | The campaign list is over 2 MB. | Split the list, or send it as a file. |
VALIDATION_ERROR | 400 | A field or the Idempotency-Key header is wrong, or the time is more than 5 minutes in the past or more than 90 days ahead. fieldErrors names the field. | Fix the request and send it again, with the same id. |
UNAUTHORIZED | 401 | The key is missing, or it is revoked, disabled or expired. | Check the x-api-key header, or create a new key. |
FORBIDDEN | 403 | The request does not come from a key, or the route is closed to keys, like the console's quick call. | Ask for calls with POST /outbound-calls and a key. |
NOT_FOUND | 404 | The agent, number, call or campaign does not exist in this account, or was not asked for by a key. | Check the ids. |
INSUFFICIENT_CREDIT | 402 | A call for now, without credit. It becomes «Failed» with the reason insufficient_credit. | Add credit and send the request again. You can use the same id. |
DIDLOGIC_OUTBOUND_BLOCKED | 400 | The number's carrier does not call this destination. details.reason is destination_not_allowed. | Check the destination number. |
BAD_REQUEST | 400 | Another refusal, explained in the message and, when present, in details.reason. For example: do_not_call (the number is on your account's «Do not call» list, and nothing is created), fromNumber is missing, or the agent is not active. | Read details.reason and the message, and fix the request. |
INTERNAL_SERVER_ERROR | 503 | With 503, Atendia could not store the request and nothing was created. With 500, the call may already exist. | Send the same request again, with the same id: you get the call if it already exists. |
PAYLOAD_TOO_LARGE | 413 | The body of a call request is over 100 kB. | Shorten the request's texts. |
NOT_AFTER_IN_PAST | 400 | The notAfter deadline had already passed when the request arrived. | Check the date and the time zone of notAfter. If the appointment is already over, there is no call to ask for. |
SCHEDULED_AT_AFTER_NOT_AFTER | 400 | The scheduled time (scheduledAt) is equal to or later than the deadline (notAfter): the call could never leave. | Schedule a time before the deadline, or check the dates and the time zones. |
Why a call failed
A FAILED call carries the reason in reason, from a closed list. The console shows the same reason, as text. New reasons may appear: treat a reason you do not know as a failure.
| Reason | In the console | When |
|---|---|---|
cancelled | Cancelled | You cancelled the call, by key or in the console. |
campaign_cancelled | Campaign cancelled | The campaign was cancelled before this call left. |
dial_failed | The call did not connect | The call never connected (refused by the carrier or a failure on Atendia's side). |
dial_outcome_uncertain | No confirmation that it connected | It is not known whether the dial reached the carrier. Atendia does not dial again: you decide whether to ask for another call. |
agent_unavailable | Agent unavailable | The agent was deleted or deactivated, or stopped during the call. |
source_number_unavailable | Source number unavailable | The calling Atendia number is no longer active, or moved to another account. |
destination_not_allowed | Destination not allowed | The number's carrier does not call this destination. |
destination_rule_missing | Carrier has no destination rule | The number's carrier has no destination rule. |
plan_minutes_exhausted | Plan minutes used up | No longer used. It appears only on old calls, from when there were plan minutes. |
insufficient_credit | Not enough credit | A request for now, without credit, refused in its own answer. |
dispatch_interrupted | Dispatch interrupted | Leaving was interrupted several times on Atendia's side. |
import_rejected | Rejected at import | In a campaign, the contact was refused when the list was read. |
deadline_passed | Past the deadline | The request's “do not call after” deadline passed before the call left. |
do_not_call | On the «Do not call» list | The number is on your account's «Do not call» list. The call is not made and there is no new attempt. In a campaign, the contact is refused as soon as the list is read. |
import_failed | The campaign's list was not imported | In a campaign, reading the list failed for good. The campaign is «Failed» and the remaining calls are not made. |
What the law asks
A note on the law: calls to consumers between 9 am and 10 pm, say who you are right away, and have prior consent for marketing calls. Atendia does not block any of this; the choice is yours. For example, start the virtual assistant's first sentence with your company's name.
Examples
Make
- In the scenario, add the «HTTP» → «Make a request» module. URL:
https://api.atendia.pt/api/v1/outbound-calls. Method:POST. - Headers:
x-api-keywith your key, andIdempotency-Keywith one value per call, for example the booking id followed by-reminder. Do not share the scenario with the key inside it. - Body: «Body type»
Raw, «Content type»JSON (application/json), and the request's JSON, with the values from the previous module. - Turn on «Parse response» to read
outboundIdandstatusin the next modules. Raise the module's timeout, because a request for now can take up to about 2 minutes. - To receive the result, create another scenario that starts with «Custom webhook» and put its address in the agent's «Post-call webhook». Use
outboundIdorreferenceto find the booking.
n8n
- Add the «HTTP Request» node. Method
POST, URLhttps://api.atendia.pt/api/v1/outbound-calls. - Authentication: «Generic Credential Type» → «Header Auth», with the name
x-api-keyand your key as the value. That way the key is stored in a credential. - Turn on «Send Headers» and add
Idempotency-Key, with an expression that gives one value per call, for example from the booking id. - Turn on «Send Body», with «Body Content Type»
JSON, and fill in the request. Under «Options», raise «Timeout» to 180,000 ms. - To receive the result, create another workflow with the «Webhook» node, publish it and put its production address in the agent's «Post-call webhook».
Code
The examples read the key from the ATENDIA_API_KEY environment variable. The ids and the number are examples.
curl: ask for a call
# Placeholder: put the key the console showed you here, never in a file you share.
export ATENDIA_API_KEY="atd_xxxxxxxxxxxxxxxxxxxxxxxx"
curl -X POST https://api.atendia.pt/api/v1/outbound-calls \
-H "x-api-key: $ATENDIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: marcacao-4821-lembrete" \
-d '{
"agentId": "00000000-0000-4000-8000-000000000000",
"phoneNumber": "+351210000000",
"scheduledAt": "2026-11-17T15:00:00+00:00",
"notAfter": "2026-11-18T15:00:00+00:00",
"dynamicVariables": { "data_consulta": "18 de novembro de 2026, às 15h00" },
"reference": "marcacao-4821"
}'Node: ask for a call
// Node 18 or later. The key comes from the environment, never from the code.
const response = await fetch("https://api.atendia.pt/api/v1/outbound-calls", {
method: "POST",
headers: {
"x-api-key": process.env.ATENDIA_API_KEY,
"Content-Type": "application/json",
// One value per call: a repeated request never calls twice.
"Idempotency-Key": "marcacao-4821-lembrete",
},
body: JSON.stringify({
agentId: "00000000-0000-4000-8000-000000000000",
phoneNumber: "+351210000000",
scheduledAt: "2026-11-17T15:00:00+00:00",
// Never call after the appointment itself.
notAfter: "2026-11-18T15:00:00+00:00",
dynamicVariables: { data_consulta: "18 de novembro de 2026, às 15h00" },
reference: "marcacao-4821",
}),
// A call due now can take up to about 2 minutes to answer.
signal: AbortSignal.timeout(180_000),
});
const answer = await response.json();
if (!response.ok) {
// Decide by the HTTP status and the code, never by the message.
throw new Error(`${response.status} ${answer.code}`);
}
console.log(answer.data.outboundId, answer.data.status);
curl: find by reference
curl "https://api.atendia.pt/api/v1/outbound-calls?reference=marcacao-4821" \
-H "x-api-key: $ATENDIA_API_KEY"curl: cancel a call
curl -X POST https://api.atendia.pt/api/v1/outbound-calls/11111111-1111-4111-8111-111111111111/cancel \
-H "x-api-key: $ATENDIA_API_KEY"