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

A 34 character string that uniquely identifies this fax.

accountSid
sid<AC> Not PII

The unique SID identifier of the Account.

from

The number the fax was sent from, in E.164 format, or the SIP From display name.

to

E.164 'To' number - the phone number that received the fax, or a SIP URI

quality
enum:quality Not PII

One of the Fax Quality values

mediaSid
sid<ME> Not PII

A 34-character unique identifier prefixed with "ME" that references the media instance associated with this Fax instance

mediaUrl
string Not PII

Twilio-hosted URL that can be used to download media (note that this URL will expire after 2 hours, but a new URL can be fetched from the instance resource)

numPages
integer? Not PII

The number of pages contained in the fax document

duration
integer? Not PII

The time taken to transmit the fax, in seconds.

status
enum:status Not PII

The status of this fax. One of queued, processing, sending, delivered, receiving, received, no-answer, busy, failed or canceled.

direction
enum:direction Not PII

The transmission direction of this fax. One of 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 this fax, in price_unit units.

priceUnit
currency Not PII

The ISO 4217 currency code used to price the fax

dateCreated
date_time<iso8601> Not PII

An ISO 8601 date and time for when the fax was created

dateUpdated
date_time<iso8601> Not PII

An ISO 8601 date and time for when the fax was last updated

links
uri_map Not PII

Contains a dictionary of URL links to nested resources of this fax.

url
url Not PII

The URL of this 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

        A 34 character string that uniquely identifies this fax.

        status
        Optional
        post enum:update_status Not PII

        The updated status of this fax. The only valid option is canceled. This may fail if the status has already started transmission.

        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

              Filters the returned list to only include faxes sent from the supplied number, given in E.164 format.

              to
              Optional
              get string PII MTL: 120 DAYS

              Filters the returned list to only include faxes sent to the supplied number, given in E.164 format.

              dateCreatedOnOrBefore
              Optional
              get date_time<iso8601> Not PII

              Filters the returned list to only include faxes created on or before the supplied date, given in ISO 8601 format.

              dateCreatedAfter
              Optional
              get date_time<iso8601> Not PII

              Filters the returned list to only include faxes created after the supplied date, given 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 or SIP address to send the fax to, E.164-formatted.

                    mediaUrl
                    Required
                    post url Not PII

                    The HTTP or HTTPS URL where the fax media PDF resides that Twilio will make a GET request to. (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

                    A quality value, which defaults to fine

                    statusCallback
                    Optional
                    post url Not PII

                    A status callback URL that will receive a POST when the status of the fax changes

                    from
                    Optional
                    post string PII MTL: 120 DAYS

                    The phone number to use as the caller id, E.164-formatted. If using a phone number, it must be a Twilio number or a verified outgoing caller id for your account. If sending to a SIP address, this can be any alphanumeric string (plus the characters +, _, ., and -) to use in the From header of the SIP request.

                    sipAuthUsername
                    Optional
                    post string Not PII

                    The username to use for authentication when sending to a SIP address.

                    sipAuthPassword
                    Optional
                    post string Not PII

                    The password to use for authentication when sending to a SIP address.

                    storeMedia
                    Optional
                    post boolean Not PII

                    Whether or not to store a copy of the sent media on Twilio's servers for later retrieval (defaults to true)

                    ttl
                    Optional
                    post integer Not PII

                    How many minutes from when a fax was initiated should Twilio attempt to send a 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.

                          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.