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 EXAMPLES

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

Numbers^API

HTTP ENDPOINTS

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

Getting Started with Programmable Fax API

Requirements

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

Glossary

Term	Description
Connection	Used to configure inbound traffic and authentication for one or more phone numbers.
Outbound Profile	Used to configure outbound traffic and billing for one or more phone numbers.
Webhook	An HTTP callback used to notify your server that you have received a message.

Guided Example

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

Sending 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/faxes.

Authentication

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.

Header	Description
media_url	The URL to the PDF used for the fax's media.
connection_id	The connection ID to send the fax with.
to	The fax enabled phone number, in E.164 format, the fax will be sent to or SIP URI.
from	The phone number, in E.164 format, the fax will be sent from.
Authorizaton: Beareer	The prefix to your API V2 key created in Step 2.

Available 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 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 Code	Message	Description
200	OK	The request succeeded.
403	Forbidden	The request was valid, however the user is not authorized to perform this action.
404	Not Found	The requested resource could not be found.
422	Invalid Parameters	The request has invalid parameters.

Example: 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 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 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 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"
  }
}

Field	Value
record_type	Description of the record.
id	unique id for the webhook
event_type	The type of event
occured_at	ISO-8601 datetime of when event was created
to	Destination number or SIP URI of the call
from	Number or SIP URI placing the call
fax_id	Unique ID for the Programmable Fax
client_state	Configurable state to track commands
status	Can be one of `queued`, `media.processed`, `sending.started`, `delivered`, `failed`

Next: Programmable Fax Commands