Programmable Fax Commands API

Programmable fax command operations API

View a list of faxes

SecuritybearerAuth
Request
query Parameters
filter[created_at][gte]
string <date-time>

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

Example: filter[created_at][gte]=2020-02-02T22:25:27.521992Z
filter[created_at][gt]
string <date-time>

ISO 8601 date time for filtering faxes created after that date

Example: filter[created_at][gt]=2020-02-02T22:25:27.521992Z
filter[created_at][lte]
string <date-time>

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

Example: filter[created_at][lte]=2020-02-02T22:25:27.521992Z
filter[created_at][lt]
string <date-time>

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

Example: filter[created_at][lt]=2020-02-02T22:25:27.521992Z
filter[direction][eq]
string

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

Example: filter[direction][eq]=inbound
filter[from][eq]
string

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

Example: filter[from][eq]=+13127367276
page[size]
integer

Number of fax resourcxes for the single page returned

Example: page[size]=2
page[number]
integer

Number of the page to be retrieved

Example: page[number]=2
Responses
200

List faxes response

Response Schema: application/json
Array of objects (Fax)
meta
object
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/faxes
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const { data: faxes } = await telnyx.faxes.list();
Response samples
application/json
{}

Send a fax

Send a fax. Files have size limits and page count limit validations. If a file is bigger than 50MB or has more than 350 pages it will fail with file_size_limit_exceeded and page_count_limit_exceeded respectively.

Expected Webhooks:

  • fax.queued
  • fax.media.processed
  • fax.sending.started
  • fax.delivered
  • fax.failed
SecuritybearerAuth
Request
Request Body schema:
required

Send fax request

connection_id
required
string

The connection ID to send the fax with.

from
required
string (From)

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

media_name
string (MediaName)

The media_name used for the fax's media. Must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. media_name and media_url/contents can't be submitted together.

media_url
string (MediaUrl)

The URL to the PDF used for the fax's media. media_url and media_name/contents can't be submitted together.

monochrome
boolean
Default: false

The flag to enable monochrome, true black and white fax results.

quality
string (Quality)

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

store_media
boolean
Default: false

Should fax media be stored on temporary URL. It does not support media_name, they can't be submitted together.

t38_enabled
boolean
Default: true

The flag to disable the T.38 protocol.

to
required
string (To)

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

webhook_url
string

Use this field to override the URL to which Telnyx will send subsequent webhooks for this fax.

Responses
202

Send fax response

Response Schema: application/json
object (Fax)
connection_id
string (ConnectionId)

The ID of the connection used to send the fax.

created_at
string <datetime>

ISO 8601 timestamp when resource was created

direction
string (Direction)

The direction of the fax.

Enum: "inbound" "outbound"
from
string (From)

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

id
string <uuid> (Id)

Identifies the resource.

media_name
string (MediaName)

The media_name used for the fax's media. Must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. media_name and media_url/contents can't be submitted together.

media_url
string (MediaUrl)

The URL to the PDF used for the fax's media. media_url and media_name/contents can't be submitted together.

quality
string (Quality)

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

record_type
string

Identifies the type of the resource.

Value: "fax"
status
string

Status of the fax

Enum: "queued" "media.processed" "originated" "sending" "delivered" "failed" "initiated" "receiving" "media.processing" "received"
store_media
boolean

Should fax media be stored on temporary URL. It does not support media_name.

stored_media_url
string

If store_media was set to true, this is a link to temporary location. Link expires after 10 minutes.

to
string (To)

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

updated_at
string <datetime>

ISO 8601 timestamp when resource was updated

webhook_failover_url
string

Optional failover URL that will receive fax webhooks if webhook_url doesn't return a 2XX response

webhook_url
string

URL that will receive fax webhooks

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
Callbacks
postDelivered Post
postFailed Post
postMedia Processed Post
postQueued Post
postSending Started Post
post/faxes
Request samples
{}
Response samples
application/json
{}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "fax.delivered",
    • "id": "95479a2e-b947-470a-a88f-2da6dd07ae0f",
    • "occurred_at": "2020-05-05T13:08:22.039204Z",
    • "payload": {
      • "call_duration_secs": 25,
      • "connection_id": "234423",
      • "direction": "outbound",
      • "fax_id": "f8338808-3dc6-4f2b-942a-5d1f39255784",
      • "from": "+17733372107",
      • "original_media_url": "http://www.example.com/fax.pdf",
      • "page_count": 2,
      • "status": "delivered",
      • "to": "+15107882622",
      • "user_id": "19a75cea-02c6-4b9a-84fa-c9bc8341feb8"
      },
    • "record_type": "event"
    }
}

Delete a fax

SecuritybearerAuth
Request
path Parameters
id
required
string <uuid>

The unique identifier of a fax.

Responses
204

The resource was deleted successfully.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
delete/faxes/{id}
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const { data: fax } = await telnyx.faxes.retrieve("id");
fax.del();
Response samples
application/json
{
  • "errors": [
    • {
      • "code": "string",
      • "detail": "string",
      • "meta": { },
      • "source": {
        • "parameter": "string",
        • "pointer": "/json/pointer"
        },
      • "title": "string"
      }
    ]
}

View a fax

SecuritybearerAuth
Request
path Parameters
id
required
string <uuid>

The unique identifier of a fax.

Responses
200

Get fax response

Response Schema: application/json
object (Fax)
connection_id
string (ConnectionId)

The ID of the connection used to send the fax.

created_at
string <datetime>

ISO 8601 timestamp when resource was created

direction
string (Direction)

The direction of the fax.

Enum: "inbound" "outbound"
from
string (From)

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

id
string <uuid> (Id)

Identifies the resource.

media_name
string (MediaName)

The media_name used for the fax's media. Must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. media_name and media_url/contents can't be submitted together.

media_url
string (MediaUrl)

The URL to the PDF used for the fax's media. media_url and media_name/contents can't be submitted together.

quality
string (Quality)

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

record_type
string

Identifies the type of the resource.

Value: "fax"
status
string

Status of the fax

Enum: "queued" "media.processed" "originated" "sending" "delivered" "failed" "initiated" "receiving" "media.processing" "received"
store_media
boolean

Should fax media be stored on temporary URL. It does not support media_name.

stored_media_url
string

If store_media was set to true, this is a link to temporary location. Link expires after 10 minutes.

to
string (To)

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

updated_at
string <datetime>

ISO 8601 timestamp when resource was updated

webhook_failover_url
string

Optional failover URL that will receive fax webhooks if webhook_url doesn't return a 2XX response

webhook_url
string

URL that will receive fax webhooks

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/faxes/{id}
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const { data: fax } = await telnyx.faxes.retrieve("id");
Response samples
application/json
{}

Cancel a fax

Cancel the outbound fax that is in one of the following states: queued, media.processed, originated or sending

SecuritybearerAuth
Request
path Parameters
id
required
string <uuid>

The unique identifier of a fax.

Responses
202

Successful response upon accepting cancel fax command

Response Schema: application/json
result
string
404

Fax does not exist

422

Unprocessable entity

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
post/faxes/{id}/actions/cancel
Request samples 
Response samples 
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Refresh a fax
Refreshes the inbound fax's media_url when it has expired


SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
The unique identifier of a fax.


 
Request Body schema: application/json
optional
Refresh fax request


resend_webhook
boolean
 Default:  false
The flag to re-send webhook for the fax.


 
Responses 
200
Refresh fax response


Response Schema: application/json
result
string
 
404
Fax does not exist


default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/faxes/{id}/actions/refresh
Request samples 
application/json
{
  • "resend_webhook": true
}
Response samples 
application/json
{
  • "data": {
    • "result": "ok"
    }
}