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

Open SidemenuDocs
Docs
Close Sidemenu

Send a fax via APIsend-a-fax-via-api

Telnyx's Programmable Fax API lets you send and manage faxing through your application.

In this guide, you'll learn how to send a simple fax using the Programmable Fax API.

Step 1: Setup a Telnyx Account, Phone Number, and Fax Applicationstep-1--setup-a-telnyx-account--phone-number--and-fax-application

First, follow our Quickstart guide to create a Telnyx account, phone number, and Fax Application.

Step 2: API Authenticationstep-2--api-authentication

If you already have a Telnyx V2 API Authentication key, skip to Step 3.

  1. 1In the Telnyx Mission Control PortalTelnyx Developers, in the left menu bar navigate to "Auth".
  2. 2Ensure, API V2 is selected in the horizontal menu bar.
  3. 3Click "Create API key"
  4. 4Copy the API key and save it somewhere safe.

Step 3: Send a PDF using Programmable Fax API using curlstep-3--send-a-pdf-using-programmable-fax-api-using-curl

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.

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.

Now that we know what we need to include in our request, we can use a number of different methods to structure and send it. In this example, we are going to use curl straight from the command line. You can also use a client such as PostmanTelnyx Developers to structure your request.

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"

Step 4: Verify HTTP response and receive webhooksstep-4--verify-http-response-and-receive-webhooks

If you have successfully structured your command and the fax has begun sending, the Programmable Fax API will respond with HTTP 200.

If you do not receive a HTTP 200 response, double-check your request and try again!

Once the request to send the fax has been successfullly received by Telnyx, you should begin receiving a series of webhooks to the URL that you specified in your Call Control (Fax) application configured in Step 2.

The webhooks you should receive are:

  • fax.queued
  • fax.media.processed
  • fax.sending.started
  • fax.delivered
  • fax.failed

Step 5: Sit back and enjoy your new Programmable Fax solution!step-5--sit-back-and-enjoy-your-new-programmable-fax-solution-

Was this page helpful?was-this-page-helpful