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:

account_sid
sid<AC> Not PII

The unique SID identifier of the Account.

api_version
string Not PII

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

date_created
date_time<iso8601> Not PII

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

date_updated
date_time<iso8601> Not PII

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

direction
enum:direction Not PII

The transmission direction of this fax. One of inbound or outbound.

duration
integer? Not PII

The time taken to transmit the fax, in seconds.

from

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

links
uri_map Not PII

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

media_sid
sid<ME> Not PII

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

media_url
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)

num_pages
integer? Not PII

The number of pages contained in the fax document

price
decimal Not PII

The price billed to transmit this fax, in price_unit units.

price_unit
currency Not PII

The ISO 4217 currency code used to price the fax

quality
enum:quality Not PII

One of the Fax Quality values

sid
sid<FX> Not PII

A 34 character string that uniquely identifies this fax.

status
enum:status Not PII

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

to

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

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

Loading Code Sample...
      
      
      
      

      HTTP POST

      Updates a single Fax instance.

      Optional Parameters

      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

      Loading Code Sample...
          
          
          
          

          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

          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.

          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.

          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.

          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

          Loading Code Sample...
              
              
              
              

              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

              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)

              To
              Required
              post string PII MTL: 120 DAYS

              The phone number or SIP address to send the fax to, E.164-formatted.

              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.

              Quality
              Optional
              post enum:quality Not PII

              A quality value, which defaults to fine

              SipAuthPassword
              Optional
              post string Not PII

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

              SipAuthUsername
              Optional
              post string Not PII

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

              StatusCallback
              Optional
              post url Not PII

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

              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

              Loading Code Sample...
                  
                  
                  
                  

                  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.

                  Loading Code Sample...