Fax Resource
We have made the difficult decision to disable Programmable Fax for all accounts on December 17, 2021. For new and inactive accounts, access to Programmable Fax is disabled effective immediately. We recognize the challenges this decision might cause and have provided detailed migration plans to prevent disruptions.
For Japan customers, please refer to this migration plan. For all other customers, please refer to this migration plan. Learn more.
The Fax resource is the main point of interaction between you and the Fax REST API.
Fax properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the Fax resource. |
account_sid
|
The SID of the Account that created the Fax resource. |
from
|
The number the fax was sent from. Can be the phone number in E.164 format or the SIP |
to
|
The phone number that received the fax in E.164 format or a SIP URI. |
quality
|
The Fax Quality value that describes the fax quality. Can be: |
media_sid
|
The SID of the FaxMedia resource that is associated with the Fax. |
media_url
|
The Twilio-hosted URL that can be used to download fax media. Note this URL expires after 2 hours. A new URL can be fetched from the instance resource if necessary. |
num_pages
|
The number of pages contained in the fax document. |
duration
|
The time in seconds it took to transmit the fax. |
status
|
The status of the fax. Can be: |
direction
|
The transmission direction of the fax. Can be: |
api_version
|
The API version used to transmit the fax. For this version of the API, it will always be |
price
|
The price billed to transmit the fax, specified in |
price_unit
|
The ISO 4217 code of the currency used to price the fax. |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
links
|
The URLs of the fax's related resources. |
url
|
The absolute URL of the fax resource. |
Fax Status
| Value | Description |
|---|---|
| queued | The fax is queued, waiting for processing |
| processing | The fax is being downloaded, uploaded, or transcoded into a different format |
| sending | The fax is in the process of being sent |
| delivered | The fax has been successfuly delivered |
| receiving | The fax is in the process of being received |
| received | The fax has been successfully received |
| no-answer | The outbound fax failed because the other end did not pick up |
| busy | The outbound fax failed because the other side sent back a busy signal |
| failed | The fax failed to send or receive |
| canceled | The fax was canceled, either by using the REST API, or rejected by TwiML |
Fax Quality
| Value | Case-sensitive | Description |
|---|---|---|
| standard | True | A low quality (204x98) fax resolution that should be supported by all devices |
| fine | True | (Default) A medium quality (204x196) fax resolution; this quality boasts wide device support |
| superfine | True | A high quality (204x392) fax resolution; this quality may not be supported by many devices |
Subresources
The Fax instance contains one subresource, the Fax Media Resource.
Create a Fax resource
https://fax.twilio.com/v1/Faxes
Creates a new Fax instance resource and triggers the sending of a fax.
In addition to regular phone numbers, faxes can also be sent to SIP URIs. For more information, please see Sending Faxes to SIP Destinations.
Return Values
Returns 201 with a single new Fax instance resource with status queued and a newly-generated FaxSid.
Returns 403 if the From number is not valid for use as a From number, or if the To number is blocked or not reachable in accordance with the account's international permissions.
Returns 422 if the From or To parameters are not valid E.164-formatted phone numbers, if the Quality value is not valid, or if any of the MediaUrl or StatusCallback parameters are not well-formed URLs.
Status Callback
If a StatusCallback URL is provided, Twilio will make an asynchronous HTTP request with one of the following statuses:
Delivered : The fax was successfully delivered
or
Failed: The fax failed. The ErrorCode and ErrorMessage parameters will be included in the callback when FaxStatus=failed.
Twilio also includes of the following form parameters in the request:
| Parameter | Description |
|---|---|
| FaxSid | The 34-character unique identifier for the fax |
| AccountSid | The account from which the fax was sent |
| From | The caller ID or SIP From display name |
| To | The phone number or SIP URI of the destination |
| RemoteStationId | The called subscriber identification (CSID) reported by the receiving fax machine |
| FaxStatus | The current status of the fax transmission |
| ApiVersion | The API version used to send the fax, which for this API will be "v1" |
| OriginalMediaUrl | The original URL passed when sending the fax |
| NumPages | The number of pages sent (only if successful) |
| MediaUrl | A media URL on Twilio's servers that can be used to fetch the original media sent. Note that this URL will expire after 2 hours, but a new URL can be fetched from the instance resource |
| ErrorCode | A Twilio error code that gives more information about a failure, if any |
| ErrorMessage | A detailed message describing a failure, if any |
Parameters
| Parameters in REST API format | |
|---|---|
to
Required
|
The phone number to receive the fax in E.164 format or the recipient's SIP URI. |
media_url
Required
|
The URL of the PDF that contains the fax. See our security page for information on how to ensure the request for your media comes from Twilio. |
quality
Optional
|
The Fax Quality value that describes the fax quality. Can be: |
status_callback
Optional
|
The URL we should call using the |
from
Optional
|
The number the fax was sent from. Can be the phone number in E.164 format or the SIP |
sip_auth_username
Optional
|
The username to use with the |
sip_auth_password
Optional
|
The password to use with |
store_media
Optional
|
Whether to store a copy of the sent media on our servers for later retrieval. Can be: |
ttl
Optional
|
How long in minutes from when the fax is initiated that we should try to send the fax. |
Example 1
Fetch a Fax resource
https://fax.twilio.com/v1/Faxes/{Sid}
Fetch a Fax resource
Return Values
Returns 200 with a single Fax instance resource if the FaxSid was found.
Returns 404 if the FaxSid was not found.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The Twilio-provided string that uniquely identifies the Fax resource to fetch. |
Example 1
Read multiple Fax resources
https://fax.twilio.com/v1/Faxes
Lists Faxes in the account
Return Values
Returns 200 with a list resource (under the key faxes) with standard Twilio paging information (the list may be empty if no faxes match the requested filters).
Returns 422 if the From or To parameters are not valid E.164-formatted phone numbers.
Parameters
| Parameters in REST API format | |
|---|---|
from
Optional
|
Retrieve only those faxes sent from this phone number, specified in E.164 format. |
to
Optional
|
Retrieve only those faxes sent to this phone number, specified in E.164 format. |
date_created_on_or_before
Optional
|
Retrieve only those faxes with a |
date_created_after
Optional
|
Retrieve only those faxes with a |
Example 1
Update a Fax resource
https://fax.twilio.com/v1/Faxes/{Sid}
Updates a single Fax instance.
Return Values
Returns 200 with a single Fax instance resource on success.
Returns 400 if the Status value is not valid or supported.
Returns 404 if the FaxSid was not found.
Returns 409 if the status cannot be updated because the fax has already completed or failed. Note: currently faxes cannot be canceled once sending has begun.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The Twilio-provided string that uniquely identifies the Fax resource to update. |
status
Optional
|
The new status of the resource. Can be only |
Example 1
Delete a Fax resource
https://fax.twilio.com/v1/Faxes/{Sid}
Deletes this Fax instance and any associated Fax Media instance. Note that this action cannot be undone, so it should be taken with care.
Return Values
Returns 204 if this resource and its subresources were successfully deleted, had been deleted previously, or were not found.
Returns 409 if the Fax instance has not yet moved into a completed state and cannot yet be deleted.
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The Twilio-provided string that uniquely identifies the Fax resource to delete. |
Example 1
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.