Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Fax Resource

The Fax resource is the main point of interaction between you and the Fax REST API.

Fax properties

Names in PHP format
sid
sid<FX> Not PII

The unique string that we created to identify the Fax resource.

accountSid
sid<AC> Not PII

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 from display name.

to

The phone number that received the fax in E.164 format or a SIP URI.

quality
enum:quality Not PII

The Fax Quality value that describes the fax quality. Can be: standard, fine, or superfine.

mediaSid
sid<ME> Not PII

The SID of the FaxMedia resource that is associated with the Fax.

mediaUrl
string Not PII

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.

numPages
integer? Not PII

The number of pages contained in the fax document.

duration
integer? Not PII

The time in seconds it took to transmit the fax.

status
enum:status Not PII

The status of the fax. Can be: queued, processing, sending, delivered, receiving, received, no-answer, busy, failed or canceled.

direction
enum:direction Not PII

The transmission direction of the fax. Can be: inbound or outbound.

apiVersion
string Not PII

The API version used to transmit the fax. For this version of the API, it will always be v1.

price
decimal Not PII

The price billed to transmit the fax, specified in price_unit units.

priceUnit
currency Not PII

The ISO 4217 code of the currency used to price the fax.

dateCreated
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

dateUpdated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

links
uri_map Not PII

The URLs of the fax's related resources.

url
url Not PII

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

post
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 blacklisted 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

The status callback sent to your server by Twilio will be a POST request using the application/x-www-form-urlencoded content type, and will include the following form parameters.

Please note, when requesting Status Callbacks with an outbound fax, you will receive 2 separate callbacks to your URL for the following statuses:

Queued: Twilio has accepted your API request, and has queued your fax for processing.

Delivered or Failed: The fax request has been completed successfully, or it has failed.

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
Names in None format
to
Required
post string PII MTL: 120 DAYS

The phone number to receive the fax in E.164 format or the recipient's SIP URI.

media_url
Required
post url Not PII

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
post enum:quality Not PII

The Fax Quality value that describes the fax quality. Can be: standard, fine, or superfine and defaults to fine.

status_callback
Optional
post url Not PII

The URL we should call using the POST method to send status information to your application when the status of the fax changes.

from
Optional
post string PII MTL: 120 DAYS

The number the fax was sent from. Can be the phone number in E.164 format or the SIP from value. The caller ID displayed to the recipient uses this value. If this is a phone number, it must be a Twilio number or a verified outgoing caller id from your account. If to is a SIP address, this can be any alphanumeric string (and also the characters +, _, ., and -), which will be used in the from header of the SIP request.

sip_auth_username
Optional
post string Not PII

The username to use with the sip_auth_password to authenticate faxes sent to a SIP address.

sip_auth_password
Optional
post string Not PII

The password to use with sip_auth_username to authenticate faxes sent to a SIP address.

store_media
Optional
post boolean Not PII

Whether to store a copy of the sent media on our servers for later retrieval. Can be: true or false and the default is true.

ttl
Optional
post integer Not PII

How long in minutes from when the fax is initiated that we should try to send the fax.

Example 1
        
        
        
        

        Fetch a Fax resource

        get
        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
        Names in None format
        sid
        Required
        get sid<FX> Not PII

        The Twilio-provided string that uniquely identifies the Fax resource to fetch.

        Example 1
              
              
              
              

              Read multiple Fax resources

              get
              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
              Names in None format
              from
              Optional
              get string PII MTL: 120 DAYS

              Retrieve only those faxes sent from this phone number, specified in E.164 format.

              to
              Optional
              get string PII MTL: 120 DAYS

              Retrieve only those faxes sent to this phone number, specified in E.164 format.

              date_created_on_or_before
              Optional
              get date_time<iso8601> Not PII

              Retrieve only those faxes with a date_created that is before or equal to this value, specified in ISO 8601 format.

              date_created_after
              Optional
              get date_time<iso8601> Not PII

              Retrieve only those faxes with a date_created that is later than this value, specified in ISO 8601 format.

              Example 1
                    
                    
                    
                    
                    Retrieves all faxes in the account

                    Read multiple Fax resources

                    Retrieves all faxes in the account

                    Update a Fax resource

                    post
                    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
                    Names in None format
                    sid
                    Required
                    post sid<FX> Not PII

                    The Twilio-provided string that uniquely identifies the Fax resource to update.

                    status
                    Optional
                    post enum:update_status Not PII

                    The new status of the resource. Can be only canceled. This may fail if transmission has already started.

                    Example 1
                          
                          
                          
                          

                          Delete a Fax resource

                          delete
                          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
                          Names in None format
                          sid
                          Required
                          delete sid<FX> Not PII

                          The Twilio-provided string that uniquely identifies the Fax resource to delete.

                          Example 1
                                
                                
                                
                                
                                Deletes the specified Fax resource and its associated Fax Media resources

                                Delete a Fax resource

                                Deletes the specified Fax resource and its associated Fax Media resources
                                Rate this page:

                                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.