> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get outbound call status
Retrieve the current status of an outbound call, using the `call_sid` returned when the call was placed. Poll this endpoint until the status reaches a terminal value — `success` or `failure`.
## Call statuses
| Status | Description |
| - | - |
| `queued` | The call has been accepted and is queued for dialing. |
| `calling` | PolyAI is dialing the destination number. |
| `success` | The call connected and completed successfully. |
| `failure` | The call did not connect or ended in an error. |
When `status` is `failure`, the response also carries a `failure_code` — a closed set of machine-readable causes you can branch on. The `reason` field is free text with no stability contract, so classify on `failure_code` rather than parsing it.
## Failure codes
Six failures happen before the destination carrier replies at all:
| `failure_code` | Meaning |
| - | - |
| `queue_timeout` | The call waited in the dialing queue past its timeout. |
| `originate_timeout` | The request to originate the call timed out. |
| `status_lookup_timeout` | PolyAI could not read the call's outcome in time. |
| `status_lookup_failed` | PolyAI hit an error reading the call's outcome. |
| `retry_failed` | A retry of the call attempt failed. |
| `max_retries_exceeded` | The call was retried up to its limit without connecting. |
The rest are mapped from the SIP response the call ended on:
| `failure_code` | SIP code | Meaning |
| - | - | - |
| `invalid_number` | 404 | The destination number does not exist. |
| `unavailable` | 480 | The destination is temporarily unavailable. |
| `busy` | 486 | The destination is busy. |
| `no_answer` | 487 | The call was not answered before it was cancelled. |
| `declined` | 603 | The callee declined the call. |
| `rejected` | 403 | The trunk refused the call, typically an unauthorized caller ID. |
| `carrier_error` | 5xx | The carrier returned a server error. |
| `unknown` | other | Any other SIP code, or a cause this API cannot yet name. |
Members may be added to `failure_code` without a major version bump. Treat any value you do not recognise as `unknown` rather than failing on it.
`rejected` and `declined` are deliberately separate: a 403 is your trunk refusing the caller ID you presented — a configuration error that will fail identically on every retry — while a 603 is a person hanging up. The lookup timeouts, by contrast, are transient; the same call placed again later may well connect.
## SIP response detail
Failures that ended on a SIP response also carry a `sip` object with the carrier's reply. It is absent for failures that never reached one, such as `status_lookup_timeout`.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"status": "failure",
"reason": "call failed: SIP 403 Caller ID is unauthorized",
"failure_code": "rejected",
"sip": {
"code": "403",
"reason": "Caller ID is unauthorized"
}
}
```
`sip.reason` is the carrier's own reason phrase. It is unvalidated and not under PolyAI's control, so escape it before displaying it or writing it anywhere it could be interpreted as markup.
Call statuses are retained for roughly **2 hours** after the call is placed. After that the `call_sid` is no longer queryable and the endpoint returns `404`.
## OpenAPI
````yaml GET /v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}
openapi: 3.0.3
info:
title: PolyAI SIP Trunking API
version: 1.0.0
description: Management API for PolyAI SIP Trunks and their Extensions.
servers:
- url: https://api.us.poly.ai
description: US region
- url: https://api.eu.poly.ai
description: EU region
- url: https://api.uk.poly.ai
description: UK region
security:
- polyApiKey: []
tags:
- name: SIP Trunks
description: >-
A SIP Trunk is a virtual connection between your telephony platform and
PolyAI. It authenticates callers, accepts inbound calls, and holds the
list of Extensions that map a dialed number to a PolyAI agent.
- name: SIP Trunk Extensions
description: >-
An Extension binds a dialed number on a trunk to a PolyAI agent. When a
call reaches a trunk, the dialed user part is matched against that trunk's
extensions to pick the agent.
- name: Outbound Calls
description: Place and query outbound calls that route over a SIP Trunk.
paths:
/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}:
parameters:
- $ref: '#/components/parameters/trunkId'
- $ref: '#/components/parameters/callSid'
get:
tags:
- Outbound Calls
summary: Get outbound call status
operationId: getOutboundCallStatus
responses:
'200':
description: The call's current status.
content:
application/json:
schema:
$ref: '#/components/schemas/CallStatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
parameters:
trunkId:
name: trunkId
in: path
required: true
description: The SIP Trunk's friendly ID (e.g. tr-...).
schema:
type: string
callSid:
name: callSid
in: path
required: true
description: The identifier returned when the call was placed.
schema:
type: string
schemas:
CallStatusResponse:
type: object
description: The current status of an outbound call.
properties:
status:
type: string
description: The call's current status.
enum:
- queued
- calling
- success
- failure
example: failure
reason:
type: string
description: >-
Human-readable detail for the status. Free text, with no stability
contract — classify on `failure_code` rather than parsing this.
example: 'call failed: SIP 403 Caller ID is unauthorized'
failure_code:
type: string
description: >-
Why the call failed, set whenever `status` is `failure`. Members may
be added without a major version bump, so treat an unrecognised
value as `unknown`.
enum:
- queue_timeout
- originate_timeout
- status_lookup_timeout
- status_lookup_failed
- retry_failed
- max_retries_exceeded
- busy
- no_answer
- unavailable
- invalid_number
- declined
- rejected
- carrier_error
- unknown
example: rejected
sip:
$ref: '#/components/schemas/SipReply'
required:
- status
SipReply:
type: object
description: >-
The SIP response the call attempt ended on. Present only when the
carrier replied; a call that failed before reaching one has none.
properties:
code:
type: string
description: The SIP response code, e.g. `403`.
example: '403'
reason:
type: string
description: >-
The carrier's reason phrase, unvalidated and not under PolyAI's
control. Escape it before display.
example: Caller ID is unauthorized
required:
- code
Error:
type: object
description: Error response body.
properties:
success:
type: boolean
error:
type: string
message:
type: string
required:
- success
- error
- message
responses:
Unauthorized:
description: Missing or invalid credential.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Caller is not a telephony admin on the account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
polyApiKey:
type: apiKey
in: header
name: X-API-Key
````