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

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