Get outbound call status

GET

telephony

sip-trunks

{trunkId}

outbound-call

{callSid}

Get outbound call status

curl --request GET \
  --url https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid} \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "status": "failure",
  "reason": "call failed: SIP 403 Caller ID is unauthorized",
  "failure_code": "rejected",
  "sip": {
    "code": "403",
    "reason": "Caller ID is unauthorized"
  }
}

{
  "success": true,
  "error": "<string>",
  "message": "<string>"
}

{
  "success": true,
  "error": "<string>",
  "message": "<string>"
}

{
  "success": true,
  "error": "<string>",
  "message": "<string>"
}

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.

{
  "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.

Authorizations

X-API-Key

string

header

required

Path Parameters

trunkId

string

required

The SIP Trunk's friendly ID (e.g. tr-...).

callSid

string

required

The identifier returned when the call was placed.

Response

The call's current status.

The current status of an outbound call.

status

enum<string>

required

The call's current status.

Available options:

queued,

calling,

success,

failure

Example:

"failure"

reason

string

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

enum<string>

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.

Available options:

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

object

The SIP response the call attempt ended on. Present only when the carrier replied; a call that failed before reaching one has none.

Show child attributes

Last modified on September 22, 2026

⌘I

Get outbound call status

curl --request GET \
  --url https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid} \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.us.poly.ai/v1/telephony/sip-trunks/{trunkId}/outbound-call/{callSid}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "status": "failure",
  "reason": "call failed: SIP 403 Caller ID is unauthorized",
  "failure_code": "rejected",
  "sip": {
    "code": "403",
    "reason": "Caller ID is unauthorized"
  }
}

{
  "success": true,
  "error": "<string>",
  "message": "<string>"
}

{
  "success": true,
  "error": "<string>",
  "message": "<string>"
}

{
  "success": true,
  "error": "<string>",
  "message": "<string>"
}

API reference

Build & deploy

Runtime & data

Monitoring

Legacy

Call statuses

Failure codes

SIP response detail

Authorizations

Path Parameters

Response

​Call statuses

​Failure codes

​SIP response detail

Authorizations

Path Parameters

Response

Call statuses

Failure codes

SIP response detail