Skip to main content
POST
/
faxes
JavaScript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: 'My API Key',
});

const fax = await client.faxes.create({ connection_id: '234423', from: '+13125790015', to: '+13127367276' });

console.log(fax.data);
{
  "data": {
    "record_type": "fax",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "connection_id": "c-1",
    "direction": "outbound",
    "from": "+123",
    "to": "+456",
    "media_url": "http://www.example.com/fax.pdf",
    "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",
    "preview_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b_preview.tiff?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",
    "quality": "high",
    "webhook_url": "http://www.example.com/webhooks",
    "webhook_failover_url": "",
    "status": "queued",
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "created_at": "2020-05-05T09:59:12",
    "updated_at": "2020-05-05T09:59:12"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

Send fax request

​
connection_id
string
required

The connection ID to send the fax with.

Example:

"234423"

​
to
string
required

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

Example:

"+13127367276"

​
from
string
required

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

Example:

"+13125790015"

​
media_url
string

The URL (or list of URLs) to the PDF used for the fax's media. media_url and media_name/contents can't be submitted together.

Example:

"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"

​
media_name
string

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.

Example:

"my_media_uploaded_to_media_storage_api"

​
from_display_name
string

The from_display_name string to be used as the caller id name (SIP From Display Name) presented to the destination (to number). The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If ommited, the display name will be the same as the number in the from field.

Example:

"Company Name"

​
quality
enum<string>
default:high

The quality of the fax. The ultra settings provides the highest quality available, but also present longer fax processing times. ultra_light is best suited for images, wihle ultra_dark is best suited for text.

Available options:
normal,
high,
very_high,
ultra_light,
ultra_dark
Example:

"high"

​
t38_enabled
boolean
default:true

The flag to disable the T.38 protocol.

​
monochrome
boolean
default:false

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

​
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.

​
store_preview
boolean
default:false

Should fax preview be stored on temporary URL.

​
preview_format
enum<string>
default:tiff

The format for the preview file in case the store_preview is true.

Available options:
pdf,
tiff
​
webhook_url
string

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

Example:

"https://www.example.com/server-b/"

​
client_state
string

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

Example:

"aGF2ZSBhIG5pY2UgZGF5ID1d"

Response

Send fax response

​
data
object
Example:
{
  "record_type": "fax",
  "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
  "connection_id": "c-1",
  "direction": "outbound",
  "from": "+123",
  "to": "+456",
  "media_url": "http://www.example.com/fax.pdf",
  "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",
  "preview_url": "https://s3.amazonaws.com/faxes-dev/user-1/cf4a6b52-bf8e-4945-9f49-611d0d2b083b_preview.tiff?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",
  "quality": "high",
  "webhook_url": "http://www.example.com/webhooks",
  "webhook_failover_url": "",
  "status": "queued",
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "created_at": "2020-05-05T09:59:12",
  "updated_at": "2020-05-05T09:59:12"
}