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.
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 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.
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:
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
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:
2021-03-10T13:21:20+11:00
2021-03-10T02:21:20Z
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
61281234567
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.
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:
received_at) of the most recently received faxfrom_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:
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.received_at of the accumulated list of faxes. We’ll call this new_last_recived_at.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.new_last_recived_at to last_recived_at.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.
| 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.
| 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>. |
| Parameter | optional/required | description |
|---|---|---|
grant_type |
Required | Specifies the authentication method. This must be the literal string client_credentials. |
| 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. |
| URL | https://api.fax2.com.au/v1/received_faxes https://api.fax2.com.au/v1/fax_services/{service_id}/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:
id is less than the id of some entry in the previous requestreceived_at at is earlier than the received_at property of some entry in the previous request (by up to 5 minutes)received_at is earlier (by more than 5 minutes) than the time the previous request was initiatedThe above must be considered when making repeated calls to this endpoint, to ensure no faxes are missed or processed multiple times.
| 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. |
| 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. |
| 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. |
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. |
| 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.
| name | description |
fax_id |
The id of the requested received fax, as returned from the received_faxes endpoint. |
None.
None - the entire response body is the requested fax as a document.
| URL | https://api.fax2.com.au/v1/fax_services |
Returns information for all of the fax services belonging to the account.
None
| property name | data type | description |
|---|---|---|
data |
array | List of all fax services. |
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. |
| 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.
| 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 |
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 |
| property name | data type | description |
|---|---|---|
document_id |
string | An opaque string representing the prepared document. |
pages |
number | The number of pages in the document. |
| 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 |
| 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.
| 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 +. |
| 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. |
| URL | https://api.fax2.com.au/v1/sent_faxes/{id} |
Returns information about a given outgoing fax.
| Parameter | description |
|---|---|
id |
Unique identifier of the fax, as returned from the send_fax endpoint. |
| 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.
invalid_requestThis error is returned only by the authorisation endpoint. It is returned when something is missing or invalid in the request.
invalid_clientThis error is returned only by the authorisation endpoint. It is returned when one or both of the username and password are incorrect.
invalid_endpointThis 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.
unauthorizedThe access token is missing, invalid or expired.
unsupported_grant_typeThis error is returned only by the authorisation endpoint. It is returned when the grant_type passed is invalid.
forbiddenThe account being used is not permitted to access the given resource.
Also returned by the authorisation endpoint, when the account is not enabled.
not_foundThe resource requested does not exist.
bad_parameterA supplied request parameter is invalid, a required parameter is missing, or an unknown parameter has been sent.
insufficient_creditReturned when attempting to send a fax, when the account has insufficient credit to send the fax.
unsupported_document_typeThe document type passed is not in the list of supported document types given in Supported Document Types.
empty_documentThe document as converted contains no pages to fax.
conversion_errorThe service was unable to convert the document to fax format. This can be caused by any of the following:
unknown_errorThis 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.