Sign in

v52

OpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 MB
Programmable Fax Commands

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.

Supported file formats:

  • PDF (application/pdf)
  • TIFF (application/tiff, image/tiff)
  • JPEG (image/jpeg)
  • PNG (image/png)
  • Microsoft Word .doc (application/msword)
  • Microsoft Word .docx (application/vnd.openxmlformats-officedocument.wordprocessingml.document)
  • Rich Text Format .rtf (application/rtf)
  • Plain text .txt (text/plain)

Expected Webhooks:

  • fax.queued
  • fax.media.processed
  • fax.sending.started
  • fax.delivered
  • fax.failed
post/faxes

Request body

black_thresholdinteger

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

client_statestring

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

connection_idstring required

The connection ID to send the fax with.

fromstring required

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

from_display_namestring

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.

media_namestring

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. Supported formats: PDF, TIFF, JPEG, PNG, DOC, DOCX, RTF, and TXT. media_name and media_url/contents can't be submitted together.

media_urlstring

The URL (or list of URLs) to the fax document. Supported formats: PDF, TIFF, JPEG, PNG, DOC, DOCX, RTF, and TXT. media_url and media_name/contents can't be submitted together.

monochromeboolean

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

preview_format'pdf' | 'tiff'

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

quality'normal' | 'high' | 'very_high' | 'ultra_light' | 'ultra_dark'

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.

store_mediaboolean

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

store_previewboolean

Should fax preview be stored on temporary URL.

t38_enabledboolean

The flag to disable the T.38 protocol.

tostring required

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

webhook_urlstring

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

Example request

{
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "connection_id": "234423",
  "from": "+13125790015",
  "from_display_name": "Company Name",
  "media_name": "my_media_uploaded_to_media_storage_api",
  "media_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "quality": "high",
  "to": "+13127367276",
  "webhook_url": "https://www.example.com/server-b/"
}

Response

Send fax response

Example response

{
  "data": {
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "connection_id": "c-1",
    "created_at": "2020-05-05T09:59:12Z",
    "direction": "outbound",
    "failure_reason": null,
    "from": "+123",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "internal_failure_reason": null,
    "media_url": "http://www.example.com/fax.pdf",
    "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",
    "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:12Z",
    "webhook_failover_url": "",
    "webhook_url": "http://www.example.com/webhooks"
  }
}