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

POST /faxes

JavaScript

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const fax = await client.faxes.create({
  connection_id: '234423',
  from: '[phone]',
  to: '[phone]',
});

console.log(fax.data);

202

{
  "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:12Z",
    "updated_at": "2020-05-05T09:59:12Z"
  }
}

Authorizations

Authorization · string · header · required

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

Body

application/jsonmultipart/form-data

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:

"[phone]"

from · string · required

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

Example:

"[phone]"

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.

black_threshold · integer · default: 95

The black threshold percentage for monochrome faxes. Only applicable if monochrome is set to true.

Required range: 1 <= x <= 100

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

202

application/json

Send fax response

data · object

Show child attributes

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:12Z",
  "updated_at": "2020-05-05T09:59:12Z"
}