About the Fax2 API


Fax2 API Documentation

This page documents the Fax2 API.

The API provides functionality to programmatically send and receive faxes. Endpoints are available to submit faxes for sending, and to list and download received faxes.

General info

The API runs over HTTPS and (unless otherwise specified) encodes responses in JSON.

Its base URL is https://api.fax2.com.au/v1. All endpoint URLs given are relative to this URL.

Request and Response Formats

Request parameters are expected in HTTP parameter format unless otherwise specified.

Responses are in JSON unless otherwise specified. The Content-Type response header for JSON responses is application/json; charset=utf-8.

Versioning and Compatibility

This documentation is for API version 1.1; major version 1, minor version 1.

In general, when using a specific major version of this API, any existing API functionality will remain unchanged. New functionality may be introduced into an existing version, via new endpoints or new optional parameters to existing endpoints.

The major version of the API in use is specified in the top level of the API endpoint URI, i.e. https://api.fax2.com.au/v1 for version 1.

A new minor version may be introduced without prior notice. A new minor version will in general not change existing functionality. Sepcifically, a minor version may:

  • Introduce new parameters (if not present in requests, the existing behavior is assumed)
  • Add new data in responses, by adding a new key at the top level
  • Introduce new error codes
  • Change error message text
  • Accept values for existing parameters that were not specified previously

Clients that follow this document correctly should continue to function normally when a new minor version is introduced.

When the time comes that this of the API is to be deprecated, a notification will be sent at least 6 months in advance, to provide for any necessary changes to be made to existing systems before the deprecated version is decomissioned.


With the exception of the authorisation endpoint (/oauth2/token`), all requests must be authenticated with an access token.

Authentication follows the “client credentials” method in OAuth2. You supply your Fax2 username and password to the authorization endpoint, which responds with an access token. The access token must be passed to all requests, via an Authorization: header, e.g.:

Authorization: bearer 4a2302e38d28d5231da6ad72ad7de8691e51f209f997e11a91b5ceb908911b44

Notes on data types

Most of the data types used in requests and responses are self explanatory, however there are some kinds of data that warrant clarification:

  • Dates and times. All date/time elements in requests and respones are in full ISO8601 format. No abbreviations are used or permitted, nor are fractional seconds. Thus the following formats are permitted:


    All date/time values in responses are in the latter format i.e. in UTC.

  • Fax numbers. All fax numbers in requests and responses are in a canonical form with the leading international country code, with the leading + omitted.

    For example the canonical form of the Australian number 02 8123 4567 is represented as



An error response will always come in the form of a 4xx or 5xx HTTP status code, and a response body in the following format:

	"error": "SOME_ERROR_CODE",
	"error_description": "English version of error"
	"more_info": "https://www.fax2.com.au/api/doc#error"

error is one of the error codes listed in Error Codes, and is intended for consumption by software. error_description is intended for human consumption. more_info is a link to a web page providing more information about the error code returned. The response may contain other properties, depending on the error. See Error Codes for a complete list of all possible errors and any extra properties.

Processing received faxes as they arrive

When using the API to process received faxes as they arrive, some care must be taken to ensure that no faxes are missed, and that none are processed more than once.

The API only makes one guarantee regarding sucessive calls to the received_faxes endpoint: that any fax listed in a response that was not listed in a previous response, will have a received_at time no more than 5 minutes before the lastest received_at value of any fax returned in the previous request.

To ensure that every received fax is processed once and only once, a process is required that:

  • Remembers the receive time (received_at) of the most recently received fax
  • Keeps a list of processed faxes for the 5 minutes up to that time, to check against to avoid re-processing a fax
  • each time a list if received faxes is requested, uses a from_time parameter of 5 minutes before the most recently received fax.

Following is a more precise description which is more easily translated into code.

The process will need to maintain, in persistent storage, these two items: a datetime value, say last_received_at, and a list of received fax ids, say seen_ids. Initally the seen_ids list will be empty, and the last_received_at value may be anything from some date in the past to the current time.

The process to get a list of not-yet-processed received faxes runs as a loop as follows:

  1. call the received_faxes API endpoint, passing it a from_time value of 5 minutes before the currently stored last_received_at value. Accumulate the list by repeatedly calling the endpoint via the returned next_page_url property, until that property is not returned.
  2. Determine the maximum received_at of the accumulated list of faxes. We’ll call this new_last_recived_at.
  3. For each entry in the list, if its id is not found in the seen_ids list, process it as required. Also if its received_at is at most 5 minutes before new_last_recived_at, add it to the seen_ids array.
  4. copy new_last_recived_at to last_recived_at.
  5. prune the seen_ids list by removing values not found in the accumulated list of faxes.

If you are storing a complete history of processed faxes, say in a database, this can of course be used as a list of last seen faxes. However the above procedure regarding last_received_at should still be followed to ensure no faxes are missed under any circumstances.


POST oauth2/token

URL https://api.fax2.com.au/v1/oauth2/token
Notable error codes invalid_request, unsupported_grant_type, invalid_client, forbidden

Creates and returns a new access token for authentication with the rest of the API.

Request Headers

Header optional/required description
Authorization required Use this to provide the username and password as per HTTP Basic authentication, i.e. the base64 encoding of the string <username>:<password>.

Request Parameters

Parameter optional/required description
grant_type Required Specifies the authentication method. This must be the literal string client_credentials.

Response properties

property name data type description
access_token string Holds the authorization token to be used with subsequent requests.
expires_in integer The token’s lifetime in seconds, after which it will become invalid. Authentication tokens have a default expires_in of 60 minutes (3600 seconds).
token_type string For this version of the API, holds the string bearer. This is included to comply with the OAuth specification.

GET received_faxes

URL https://api.fax2.com.au/v1/received_faxes

Returns information for received faxes.

The first variant of the endpoint URL returns matching entries for all services. The second variant returns only matching entries for a particular fax service - useful if your account has multiple fax numbers.

The list is returned in no particular order. Each request will return a maximum number of elements, set by the limit parameter. A response that has been truncated to this limit will include a next_page_url property that can be used as a complete request URL (with the Authorization request header) to request the next set of data. This process can be repeated until the last response is returned, indicated by the lack of a next_page_url property, to retrieve a complete list of faxes that satisfy the search criteria.

If multiple search criteria are passed, the entries returned will be only those that meet all of the criteria.

With regard to repeated requests with the same search criteria, there is only one guarantee that is made: that any fax entries returned in a particular request will have a receive time (received_at) no earlier than 5 minutes before the latest received_at returned in any previous request.

Notably, when an request returns an entry for a fax, which was not returned in a previous request with the same criteria, any of the following is possible:

  • The new entry’s id is less than the id of some entry in the previous request
  • The new entry’s received_at at is earlier than the received_at property of some entry in the previous request (by up to 5 minutes)
  • The new entry’s received_at is earlier (by more than 5 minutes) than the time the previous request was initiated

The above must be considered when making repeated calls to this endpoint, to ensure no faxes are missed or processed multiple times.

URL Path Parameters

Parameter description
service_id (second variant only) The id of the fax service to return received faxes for, as returned from the fax_services endpoint.

Request Parameters

Parameter optional/required description
limit optional Maximum number of entries to be returned in this request. Range is 1-1000, default is 50.
continue_from optional This is used by the next_page_url response property to facilitate pagination.
from_time optional If passed, return only entries whose received_at is on or after this time. Must be in ISO 8601 format e.g. 2021-04-13T14:48:36+10:00.
before_time optional If passed, return only entries whose received_at is before this time. Must be in ISO 8601 format.

Response properties

property name data type description
data array Array of received fax items. Each is a hash with the proprties given below. If no faxes are found meeting the given criteria, this property will be empty.
next_page_url string If present, indicates that the limit was reached and there are more entries meeting the criteria that were not returned in this response. If not present, all entries found were returned.

Element properties for elements of the data top-level property

property name data type description
id string The unique id of the fax, to be passed to other API endpoints when referencing this received fax.
to string The receiving fax number, in canonical format without the leading + e.g. 61281234567
received_at datetime The time the receiving of the fax was completed.
service_id string The id of the fax service that received the fax. This can be matched against the id field in the entries returned from a fax_services request to determine the receiving fax number.
pages integer The number of pages in the received fax.

GET received_faxes/{fax_id}/content.pdf

URL https://api.fax2.com.au/v1/received_faxes/{fax_id}/content.pdf

Responds with the received fax with the given id provided in the URL, as a PDF document. The document is returned verbatim in the response body, and thus the Content-Type of the response will be application/pdf.

URL Path Parameters

name description
fax_id The id of the requested received fax, as returned from the received_faxes endpoint.

Request Parameters


Response Parameters

None - the entire response body is the requested fax as a document.

GET fax_services

URL https://api.fax2.com.au/v1/fax_services

Returns information for all of the fax services belonging to the account.

Request Parameters


Response properties

property name data type description
data array List of all fax services.

Element properties for elements of the data top-level property

property name data type description
id string The service’s unique identifier, for use where the API accepts a service_id
fax_number string The service’s fax number. This is in international format, without the leading + character e.g. 61281234567.

POST upload_document

URL https://api.fax2.com.au/v1/upload_document
Notable error codes invalid_request, unsupported_document_type, empty_document, conversion_error

Accepts and prepares a document for sending via the send_fax endpoint.

On a sucessful response to this endpoint, the document is ready to fax. If the document cannot be converted to faxable format for any reason, it is here that the failure will occur and an error returned.

The response contains an opaque id for the prepared document. Pass this id to the send_fax endpoint to send it. The id has a limited lifetime, guaranteed to be no less than 15 minutes; under normal circumstances, there is no need for the application to be aware of the expiration of a document.

Request Headers

Header optional/required description
Content-Type required If mutipart/form-data, the Request Parameters below apply and the document(s) is/are expected to be supplied as a parameter. Otherwise, the entire body of the request is the document, and the header specifies the document’s MIME type. See below for supported document types

Request Parameters

Note, request parameters apply only if the Content-Type header is mutipart/form-data.

Parameter optional/required description
document required The document to be prepared. The parameter, being part of a multipart/form-data request, must include a Content-Type header that specifies the document’s MIME type. See below for supported document types

Response properties

property name data type description
document_id string An opaque string representing the prepared document.
pages number The number of pages in the document.

Supported document types

MIME Type Extensions Description
application/msword .doc Microsoft Word document
application/pdf .pdf Adobe Portable Document Format (PDF) document
application/postscript .ps PostScript document
application/rtf .rtf Microsoft Rich Text Format document
application/vnd.ms-excel .xls Microsoft Excel spreadsheet
application/vnd.ms-powerpoint .ppt Microsoft Powerpoint presentation
application/vnd.oasis.opendocument.presentation .odp OpenOffice/LibreOffice Impress presentation
application/vnd.oasis.opendocument.spreadsheet .ods OpenOffice/LibreOffice Calc spreadsheet
application/vnd.oasis.opendocument.text ,odt OpenOffice/LibreOffice Write document
application/vnd.openxmlformats-officedocument.wordprocessingml.document .docx Microsoft Word document
image/bmp .bmp Microsoft Windows bitmap (BMP) image
image/gif .gif Graphics Interchange Format (GIF) image
image/jpeg .jpg, .jpeg Joint Photographic Experts Group (JPEG) image
image/png .png Portable Network Graphic (PN) image
image/tiff .tif, .tiff Tagged Image File Format (TIFF) image
image/x-portable-bitmap .pnm, .pbm, .pgm Netpbm format image
text/html .htm, .html Hypertext Markup Language (HTML) document
text/plain .txt Plain text file

POST send_fax

URL https://api.fax2.com.au/v1/send_fax
Notable error codes insufficient_credit

Submits a fax for sending to the given destination.

For a fax to be accepted for submission, besides the requirements for request parameters, your account must have sufficient credit to send the fax to the given destination.

Request Parameters

Parameter optional/required description
documents[] array Actual document(s) to fax. Array of strings.
dest_number string Destination fax number. Must be in international format, with or without the leading +.

Response properties

property name data type description
id string A unique id representing the queued fax. In the future you will be able to use this to check the status of a queued fax.
pages number The number of pages in the resulting fax.

GET sent_faxes/{id}

URL https://api.fax2.com.au/v1/sent_faxes/{id}

Returns information about a given outgoing fax.

URL Path Parameters

Parameter description
id Unique identifier of the fax, as returned from the send_fax endpoint.

Response properties

property name data type description
status string A code indicating the current status of the fax, one of sending, waiting, sent, failed. See below for details.
pages integer The total number of pages in the fax.
sent_at string Present only if status is sent or failed. Gives the time the fax was complete, or the last attempt ended.
reason string Present only if the fax failed, i.e. the status property is failed, and indicates the cause of the failure. See below for possible values.
send_attempts integer The number of times the Fax2 service has attempted to send the fax. If the fax is currently being sent i.e. the status property is sending, the figure does not include the attempt currently in progress.
pages_sent integer Present only if the status property is sent or failed. Indicates the number of pages successfully transmitted. If status is failed and this property is greater than 0, the fax was partially transmitted. If status is sent, this property will be equal to pages.

The status property can be one of the following:

  • sending: The fax is in the process of being sent. The receiving number will be called shortly after the fax changes to this state.
  • waiting: The fax is waiting to be sent later. This could be because there are other faxes being sent, or because a previous attempt failed and the service is waiting a while before trying again.
  • sent: The fax was transmitted successfully. In particular this means the receiving fax machine signalled reception of the final page.
  • failed: The fax failed 3 times and the service has given up.

The codes sent and failed are “final” states, indicating that no more updates to the fax will happen.

The reason property can be one of the following:

  • busy: The number was busy.
  • no_answer: The call was not anwered.
  • no_carrier: The call was answered but a fax machine could not be detected at the receiving end.
  • dial_failed: The number could not be dialled, likely because it is invalid.
  • transmit_error: The service could not send the complete fax.
  • cancelled: The fax was cancelled by the service.
  • internal_error: An unforseen error occurred.

The codes cancelled and internal_error are given for completeness but will not be encountered under normal circumstances. In other cases the code given indicates the outcome of the last attempt made.

Error Codes


This error is returned only by the authorisation endpoint. It is returned when something is missing or invalid in the request.


This error is returned only by the authorisation endpoint. It is returned when one or both of the username and password are incorrect.


This error is returned if either the request URL is not a valid API endpoint, or the HTTP request method does not match the method required for the endpoint.


The access token is missing, invalid or expired.


This error is returned only by the authorisation endpoint. It is returned when the grant_type passed is invalid.


The account being used is not permitted to access the given resource.

Also returned by the authorisation endpoint, when the account is not enabled.


The resource requested does not exist.


A supplied request parameter is invalid, a required parameter is missing, or an unknown parameter has been sent.


Returned when attempting to send a fax, when the account has insufficient credit to send the fax.


The document type passed is not in the list of supported document types given in Supported Document Types.


The document as converted contains no pages to fax.


The service was unable to convert the document to fax format. This can be caused by any of the following:

  • The document type passed does not match the document
  • The document file is malformed
  • The document file uses a feature not supported by the service


This error is returned when the system encounters an unexpected error. It shouldn’t occur under normal circumstances, however it is mentioned here so that readers are aware of the possibility that this error may be returned.