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

Open SidemenuAPI Reference
API Reference
Close Sidemenu

Overview

Send faxes between your application and a fax machine using the Programmable Fax API.

  • Inbound fax via API is currently under development.

The Programmable Fax API enables you to:

  • Send PDF files via fax enabled numbers or applications
  • Track the delivery status of a fax sent via API
  • List and delete history of faxes sent via API

GUIDES AND EXAMPLESguides-and-examples

Check out the Docs section of our Developer Center to learn how to:

HTTP ENDPOINTShttp-endpoints

  • https://api.telnyx.com/v2/faxes/
  • https://api.telnyx.com/v2/faxes/{fax_id}

Getting Started with Programmable Fax APIgetting-started-with-programmable-fax-api

Requirementsrequirements

Outbound faxes can be initiated without the purchase or porting of a number. There are two requirements:

  • A connection configured to receive Programmable Fax API requests. For now, we will use Call Control applications to configure Programmable Fax API requests
  • An outbound profile associated with the connection that determines the destinations a fax can be sent to

Configuration and Usageconfiguration-and-usage

Telnyx Programmable Fax is enabled using Connections. You can set up several connections to differentiate between use cases.

Outbound calls, initiated through the Dial and Transfer commands, are configured through an Outbound Profile that must be created and associated with the connection. The outbound profile allows you to initiate outbound traffic, and configure how that traffic is charged, managed and to which destinations it is permitted.

To issue Programmable Fax API commands, use our HTTPS API and authenticate using the API Key/Secret associated with your Mission Control account under API Keys.

To receive Programmable Fax API webhooks, set the webhook URL on your programmable fax connection to a publicly accessible endpoint on your server.

Glossaryglossary

TermDescription
ConnectionUsed to configure inbound traffic and authentication for one or more phone numbers.
Outbound ProfileUsed to configure outbound traffic and billing for one or more phone numbers.
WebhookAn HTTP callback used to notify your server that you have received a message.
Guided Exampleguided-example

Follow our guided example to set up Programmable Fax API, send commands and receive webhooks, using the Telnyx API.

Sending Commandssending-commands

A Programmable Fax API command is sent with a fax_id. The fax_id allows a user to communicate to Telnyx the fax the user wants to take an action on.

The Telnys Programmable Fax API supports PDF files. To initiate sending the fax, we need to send the request to the Telnyx Programmable Fax API endpoint https://api.telnyx.com/v2/faxesTelnyx Developers.

Authenticationauthentication

With the request we need to send additional parameters containing authentication information so Telnyx knows which account to send the fax from and information about the destination and file being sent.

HeaderDescription
media_urlThe URL to the PDF used for the fax's media.
connection_idThe connection ID to send the fax with.
toThe fax enabled phone number, in E.164 format, the fax will be sent to or SIP URI.
fromThe phone number, in E.164 format, the fax will be sent from.
Authorizaton: BeareerThe prefix to your API V2 key created in Step 2.

Available Commands and their Expected Webhooksavailable-commands-and-their-expected-webhooks

Telnyx sends webhooks to update on the status of Programmable Fax. Webhooks will also be sent in response to requests to list and delete faxes.

Command Associated Webhooks
Send a fax fax.queued
fax.media.processed
fax.sending.started
fax.delivered
fax.failed

Response when sending commandresponse-when-sending-command

When you send a Programmable Fax API Command, you will immediately receive an http response. Responses include, but are not limited to:

HTTP Status CodeMessageDescription
200OKThe request succeeded.
403ForbiddenThe request was valid, however the user is not authorized to perform this action.
404Not FoundThe requested resource could not be found.
422Invalid ParametersThe request has invalid parameters.

Example: Sending Commandsexample--sending-commands

To send a fax, send a POST request to the https://api.telnyx.com/v2/faxes endpoint as shown in the example below.

With a API V2 Keywith-a-api-v2-key
curl -X POST https://api.telnyx.com/v2/faxes \
--data-urlencode "media_url=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" \
--data-urlencode "connection_id=1232154810234" \
--data-urlencode "to=+13129457420" \
--data-urlencode "from=+19459457421" \
--header "Authorization: Bearer APIAuthKey_fromPortal"

Receiving Webhooksreceiving-webhooks

When you send a Programmable Fax API command and receive a successful response (i.e. 200 OK), you can expect to receive a webhook. The webhook will be delivered to the primary URL specified on the Programmable Fax API application associated with the call. If that URL does not resolve, or your application returns a non 200 OK response, the webhook will be delivered to the failover URL, if one has been specified.

In order to minimize webhook delivery time, Telnyx:

  • does not enforce the order in which webhooks are delivered
  • retries webhook delivery if your application does not respond within a certain time threshold.

As a result, you may encounter:

  • out-of-order webhooks
  • simultaneous (or near simultaneous) webhooks
  • duplicate webhooks

Duplicate webhooks may cause your application to issue duplicate commands. You can instruct Telnyx to ignore duplicate commands by sending a command_id parameter as part of your commands. Commands with duplicate command_ids within 60 seconds will be ignored.

Example: Receiving a webhookexample--receiving-a-webhook

When you place an outbound fax, you will receive a number of webhooks indicating the current status of the fax. The first webhook you will receive will have A queued status indicating that Telnyx successfully received the request to send the fax.

{
  "data": {
    "event_type": "fax.queued",
    "id": "3691d047-d22a-424d-80ed-fe871981aa6d",
    "occurred_at": "2020-04-22T19:32:12.538002Z",
    "record_type": "event",
    "payload": {
      "connection_id": "7267xxxxxxxxxxxxxx",
      "fax_id": "b679398e-8b4c-46bd-8630-6797f1ab5228",
      "from": "+35319605860",
      "original_media_url": "http://www.telnyx.com/telnyx-fax/1.pdf",
      "status": "queued",
      "to": "+13129457420",
      "user_id": "a5b1dfa3-fd2e-4e02-8ea4-xxxxxxxxxxxx"
    }
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "http://example.com/webhooks"
  }
}
FieldValue
record_typeDescription of the record.
idunique id for the webhook
event_typeThe type of event
occured_atISO-8601 datetime of when event was created
toDestination number or SIP URI of the call
fromNumber or SIP URI placing the call
fax_idUnique ID for the Programmable Fax
client_stateConfigurable state to track commands
statusCan be one of queued, media.processed, sending.started, delivered, failed