Menu

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?

Faxes Resource

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

Fax Instance Resource

This resource represents faxes that have been sent or received.

Resource URL

https://fax.twilio.com/v1/Faxes/{FaxSid}

where {FaxSid} is the 34-character unique ID associated with the Fax.

Resource Properties

A Fax instance is represented by the following 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 Description
standard A low quality (204x98) fax resolution that should be supported by all devices
fine A medium quality (204x196) fax resolution; this quality boasts wide device support
superfine 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.

HTTP GET

Retrieves a single Fax instance.

Return Values

Returns 200 with a single Fax instance resource if the FaxSid was found.

Returns 404 if the FaxSid was not found.

Example

        
        
        
        

        HTTP POST

        Updates a single Fax instance.

        Optional Parameters

        Names in PHP 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.

        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.

        Example

              
              
              
              

              HTTP PUT

              Not supported.

              HTTP DELETE

              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.

              Fax List Resource

              The list resource allows you to retrieve a list of faxes sent or received, and to send new faxes.

              Resource URL

              https://fax.twilio.com/v1/Faxes
              

              HTTP GET

              Lists Faxes in the account.

              Optional Parameters

              Names in PHP 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.

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

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

              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.

              Example

                    
                    
                    
                    

                    HTTP POST

                    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.

                    Parameters

                    Names in PHP 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.

                    mediaUrl
                    Required
                    post url Not PII

                    The Twilio-hosted 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.

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

                    sipAuthUsername
                    Optional
                    post string Not PII

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

                    sipAuthPassword
                    Optional
                    post string Not PII

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

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

                    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:

                    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

                    Example

                          
                          
                          
                          

                          HTTP PUT

                          Not supported.

                          HTTP DELETE

                          Not supported.

                          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.