This is the API V2 documentation. To switch out of beta revert back to our API V1.

Telnyx DevelopersAPI v2
Sign inTelnyx Developers
Open Menu
DocsAPI ReferenceJoin Slack Community
Create an AccountSign in
Questions on setup? Talk to our experts
Open SidemenuAPI Reference
API Reference
Close Sidemenu

Programmable Fax Commands

View a list of faxesListFaxes

get https://api.telnyx.com/v2/faxes

View a list of faxes

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/faxes?filter[created_at][gte]=2020-02-02T22:25:27.521992Z&filter[created_at][gt]=2020-02-02T22:25:27.521992Z"
Parameters
In query
filter[created_at][gte]
string (date-time)
optional

ISO 8601 date time for filtering faxes created after or on that date

Example: "2020-02-02T22:25:27.521992Z"
filter[created_at][gt]
string (date-time)
optional

ISO 8601 date time for filtering faxes created after that date

Example: "2020-02-02T22:25:27.521992Z"
filter[created_at][lte]
string (date-time)
optional

ISO 8601 formatted date time for filtering faxes created on or before that date

Example: "2020-02-02T22:25:27.521992Z"
filter[created_at][lt]
string (date-time)
optional

ISO 8601 formatted date time for filtering faxes created before that date

Example: "2020-02-02T22:25:27.521992Z"
filter[direction][eq]
string
optional

The direction, inbound or outbound, for filtering faxes sent from this account

Example: "inbound"
filter[from][eq]
string
optional

The phone number, in E.164 format for filtering faxes sent from this number

Example: "+13127367276"
page[size]
integer
optional

Number of fax resourcxes for the single page returned

Example: 2
page[number]
integer
optional

Number of the page to be retrieved

Example: 2
Responses
200

List faxes response

default

Unexpected error

Success Response
{
  "data": [
    {
      "connection_id": "c-1",
      "created_at": "2020-05-05T09:59:12",
      "from": "+123",
      "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
      "media_url": "http://www.example.com/fax.pdf",
      "quality": "high",
      "record_type": "fax",
      "status": "queued",
      "store_media": true,
      "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
      "to": "+456",
      "updated_at": "2020-05-05T09:59:12",
      "webhook_failover_url": "",
      "webhook_url": "http://www.example.com/webhooks"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 1,
    "total_pages": 3,
    "total_results": 3
  }
}

Send a faxSendFax

post https://api.telnyx.com/v2/faxes

Send a fax

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"connection_id":"234423","from":"+13125790015"}' \
  https://api.telnyx.com/v2/faxes
Parameters
In body
connection_id
string
required

The connection ID to send the fax with.

Example: "234423"
media_url
string
required

The URL to the PDF used for the fax's media.

Example: "http://assets.com/FAX.pdf"
to
string
required

The phone number, in E.164 format, the fax will be sent to or SIP URI

Example: "+13127367276"
from
string
optional

The phone number, in E.164 format, the fax will be sent from.

Example: "+13125790015"
quality
string
optional

The quality of the fax. Can be normal, high, very_high

Default: "high"
Example: "high"
Responses
200

Send fax response

default

Unexpected error

Success Response
{
  "data": {
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12",
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "media_url": "http://www.example.com/fax.pdf",
    "quality": "high",
    "record_type": "fax",
    "status": "queued",
    "store_media": true,
    "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
    "to": "+456",
    "updated_at": "2020-05-05T09:59:12",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}
Expected Webhooks
fax.delivered
{
  "data": {
    "event_type": "fax.delivered",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "connection_id": "234423",
      "from": "+13125790015",
      "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
      "original_media_url": "http://assets.com/FAX.pdf",
      "status": "delivered",
      "to": "+13127367276",
      "user_id": "yfff7c54-4df3-4bca-a65a-3da1ecc777f0"
    },
    "record_type": "event"
  }
}
fax.failed
{
  "data": {
    "event_type": "fax.failed",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "connection_id": "234423",
      "failure_reason": "rejected",
      "from": "+13125790015",
      "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
      "original_media_url": "http://assets.com/FAX.pdf",
      "status": "failed",
      "to": "+13127367276",
      "user_id": "yfff7c54-4df3-4bca-a65a-3da1ecc777f0"
    },
    "record_type": "event"
  }
}
fax.media.processed
{
  "data": {
    "event_type": "fax.media.processed",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "connection_id": "234423",
      "from": "+13125790015",
      "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
      "original_media_url": "http://assets.com/FAX.pdf",
      "status": "media.processed",
      "to": "+13127367276",
      "user_id": "yfff7c54-4df3-4bca-a65a-3da1ecc777f0"
    },
    "record_type": "event"
  }
}
fax.queued
{
  "data": {
    "event_type": "fax.queued",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "connection_id": "234423",
      "from": "+13125790015",
      "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
      "original_media_url": "http://assets.com/FAX.pdf",
      "status": "queued",
      "to": "+13127367276",
      "user_id": "yfff7c54-4df3-4bca-a65a-3da1ecc777f0"
    },
    "record_type": "event"
  }
}
fax.sending.started
{
  "data": {
    "event_type": "fax.sending.started",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "connection_id": "234423",
      "from": "+13125790015",
      "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
      "original_media_url": "http://assets.com/FAX.pdf",
      "status": "sending",
      "to": "+13127367276",
      "user_id": "yfff7c54-4df3-4bca-a65a-3da1ecc777f0"
    },
    "record_type": "event"
  }
}

View a faxViewFax

get https://api.telnyx.com/v2/faxes/{id}

View a fax

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/faxes/{id}"
Parameters
In path
id
string (uuid)
required

The unique identifier of a fax.

Responses
200

Get fax response

default

Unexpected error

Success Response
{
  "data": {
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12",
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "media_url": "http://www.example.com/fax.pdf",
    "quality": "high",
    "record_type": "fax",
    "status": "queued",
    "store_media": true,
    "stored_media_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxxxxxxxx%2F20200505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200505T095917Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=fac2af40464fcc77673ad762db86e34f9c1b91a82699b5578c5327f53874df51",
    "to": "+456",
    "updated_at": "2020-05-05T09:59:12",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}

Delete a faxDeleteFax

delete https://api.telnyx.com/v2/faxes/{id}

Delete a fax

curl -X DELETE \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/faxes/{id}"
Parameters
In path
id
string (uuid)
required

The unique identifier of a fax.

Responses
204

The resource was deleted successfully.

default

Unexpected error

Was this section helpful?was-this-page-helpful