Receiving Faxes

To receive a fax, you will need:

  • An Incoming Phone Number, configured as a fax number - this will cause the number to be unavailable to receive calls using Programmable Voice
  • A FaxUrl, which will be consulted when a fax is received.

Phone Number Setup

First, ensure that you have an Incoming Phone Number on your account that supports receiving faxes. The number you select should have true for the fax item in the capabilities object, or, if using the Console, should have "Fax" listed in its capabilities.

If you don't have a fax-capable number, you'll need to purchase one. You can either use the Available Phone Numbers REST API resource (query with FaxEnabled=true) ,or Console Phone Numbers Search (check the box to search for numbers with the Fax capability) to do so.

Next, you need to configure the number's Voice Receive Mode so that the number receives faxes rather than voice calls. Again, you can either use the API's Incoming Phone Numbers resource (POST to the instance resource with VoiceReceiveMode=fax) or the Console, by selecting the phone number you want to use from the list, and changing the value of the "Accepts" dropdown box to "Faxes".

At this point, the number's VoiceUrl will now behave as its FaxUrl. Note that the number will now be unable to receive regular voice calls. (/docs/api/fax/rest/faxes#instance-delete).

TwiML

When Twilio receives a call to an incoming phone number that has been configured as a Fax number, you will receive an HTTP request to the FaxUrl configured for that number. Your server should respond with TwiML that instructs Twilio how to proceed. You can check out the parameters of the TwiML request, as well as the available <Receive> and <Reject> TwiML verbs and their usage in the TwiML documentation.

Log Storage

Twilio will store copies of media files for received faxes. The media files are available at the URL specified on the Fax instance resource.

Log data for each fax will be available via the REST API for 180 days after creation. When old fax records are pruned, Twilio will also delete the media associated with the pruned records. If you wish to delete data before that, you can delete just the media, or [the entire resource, including the media]

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.