Report a call

When a call ends, a phone system can report it to Auradonors. What happens to it is the organization’s choice on its Phone system page: keep nothing, write a note on the caller’s record, or keep a call record. 3CX reports calls through the same template it looks callers up with; any other phone system that can make an HTTP request can do the same.

It uses the same connection key as looking up a caller, sent as a bearer token.

The request

curl -X POST https://api.auradonors.com/api/integrations/v1/{tenantSlug}/phone/calls \
  -H "Authorization: Bearer aura_…" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "inbound",
    "outcome": "answered",
    "number": "+15551234567",
    "startedAt": "2026-10-14T15:02:11Z",
    "endedAt": "2026-10-14T15:06:23Z",
    "agentEmail": "[email protected]",
    "contactId": 1042,
    "callId": "pbx-88213"
  }'

The body is a JSON object or a form; every value is text or a number. Field names are matched ignoring case.

Field
`direction`	`inbound` or `outbound`.
`outcome`	`answered`, `missed` or `voicemail`.
`callType`	Instead of the two above, 3CX’s `Inbound`, `Outbound`, `Missed` or `Notanswered`.
`startedAt`	Required. A date and time; one without a zone is read as UTC.
`endedAt`	When it ended.
`duration`	Seconds, or `hh:mm:ss`. Without it, the time from start to end. A call nobody answered lasted no time.
`number`	The other party’s number, in any format.
`name`	The name your phone system has for them.
`agentEmail`	Matched to a person in Auradonors, who is then shown as having taken the call.
`agentName`	Or `agentFirstName` and `agentLastName`, when the email isn’t a person in Auradonors.
`recordingUrl`	A link to the recording. Kept only when the organization asks.
`contactId`	The contact the lookup returned. Used when that contact still has the number.
`callId`	Your own id for the call.

The response

{
  "recorded": true,
  "duplicate": false,
  "callId": "6f0d7c4e-2a5b-4f1e-9c1d-3b8a6a2f9e10",
  "contactId": 1042,
  "reason": null
}

recorded is false when the organization keeps no calls, or none of this kind (reason says which). The report still counts as the phone system getting through.
duplicate is true when Auradonors already had this call. Reporting the same call again — with the same callId, or the same direction, number, agent and start to the second — is safe: it’s kept once.
contactId is the contact the call was linked to: the one contact with its number, or the contactId you sent when that contact has it. Several people sharing the number, or nobody having it, leave it unlinked (null).

Errors

Status	When
`400`	The body isn’t JSON or a form, is over 16 KB, or doesn’t say which way the call went, how it ended or when it started.
`401`	The key is missing, malformed, replaced or belongs to another organization.
`403`	The organization’s plan doesn’t include a phone system, or the connection is switched off.
`404`	The organization’s short name isn’t known.
`429`	Too many requests with one key in a minute.
`503`	The organization’s records couldn’t be reached. Report the call again later.

Each error body is a list of { code, description }.