How to send and receive faxes with the GoFax REST API.
💡 Please first view our Getting Started with the Rest API article for a general understanding of how to use the GoFax REST API.
How to send fax
To send a single fax, send a PUT request to /v1.0/SendFax with the below example JSON payload in the body of the request.
//fax object
{
"SendTo":"61711111111", //The fax recipient
"Documents":[ //Array of fax document objects
{
"Filename":"MyFile.pdf", //Filename INCLUDING file extension. Extension is used during conversion.
"Data":"DDFEEC2CDAD2DFECG939DCBA939.......
......F301BD02CA30FD030A30E" // base64 encoded document (ASCII representation of binary data)
},
{
"Filename":"SecondFile.docx",
"Data":"<base64 encoded word doc>"
}
]
}
Your integration will need to encode documents into base64 format before submitting to our API.
If your fax was successfully submitted, you should see a response similar to below.
{
"Documents": [
{
"Filename": "MyFile.pdf",
"Message": "Initialised",
"Submitted": true
},
{
"Filename": "SecondFile.docx",
"Message": "Initialised",
"Submitted": true
}
],
"Success": true, // Query this to test whether the submission was successful.
"Message": null, //If unsuccessful, this will contain the reason.
"ValidationErrors": null, //If a document is invalid, you will see a array of errors containing the reason for each validation error
"Response": 100597945 // We recommend you store this Send Fax ID, you can use it to query status and other information later.
}
You can send multiple faxes at a time using the PUT /v1.0/SendFaxes endpoint. The JSON payload is similar to above, but is an array of fax objects instead of one.
[ //Array of fax objects
{ //First fax
"SendTo":"61711111111", //The fax recipient
"Documents":[ //Array of fax document objects
{
"Filename":"MyFile.pdf",
"Data":"<base64 encoded document>"
}
]
},
{ //Second Fax
"SendTo":"61711111112", //The fax recipient
"Documents":[ //Array of fax document objects
{
"Filename":"MyFile.pdf",
"Data":"<base64 encoded document>"
}
]
}
]
You could also supply a callback URL in your request.
...
"SendTo":"61711111111",
"CallbackUrl":"https://webhook.company.com"
...
See our Swagger UI for a full list of JSON parameters.
💡 Delete Data: If enabled when setting up your API access token, fax documents will be deleted after sending via API.
How to get fax status
It may take time for a fax to transmit to its destination, therefore the delivery status will not be returned in the initial API response and you'll need to track the status over time.
We would highly recommend Using Webhooks (a.k.a callback URLs) to be notified when a fax is delivered, alternatively you can query the status of a fax using its ID.
Using the Fax ID gathered from the "Response" field above, make a request to GET /v1.0/SendFax/{faxId}/Status, substituting "{faxId}" with your Fax ID.
Example response:
{
"InProgress": false,
"Error": false,
"ClientReference": "",
"Success": true, // Was the fax successfully sent
"Message": "Fax successfully sent", // Human readable status
"ValidationErrors": null,
"Response": null
}
Receive Fax
A inbound fax can arrive to your GoFax receive service at any time; to make your integration aware of a new received fax, you can use either an event based or poll based approach.
As mentioned above, we would highly recommend Using Webhooks (a.k.a callback URLs) to ensure your integration is notified when a new fax is received. This would require that you expose a webhook listener service for your integration.
Alternative, you could poll the GET /v1.0/ReceiveFaxes/Details endpoint to retrieve the latest 200 faxes.
There are other ReceiveFaxes endpoints that allow you to filter by date range, or limit by X number of days and increase the limit from 200 faxes.
You can also use the GET /v1.0/ReceiveFaxes/UnretrievedFaxes endpoints to get all faxes which you have not marked as retrieved (see below).
Example JSON response body:
{
"Success": true,
"Message": null,
"ValidationErrors": null,
"Response": [
{
"ID": 48242080, //The receive fax ID. Store this.
"Number": "<your fax receive number>",
"Received": "2023-04-13T12:34:55", //Datetime the fax was received by our servers.
"ReceivedUtc": "2023-04-13T02:34:55",
"Message": "COMPLETE", // Either COMPLETE or INCOMPLETE. Status of the received fax.
"SenderFaxID": "+61291989589", //The remote station ID (TSID) of sender
"SenderISDNID": "61291989589", //The Calling Line ID of sender
"TransmissionTime": 26,
"NumberOfPages": 1,
"TransmissionSpeed": 14400,
"Type": "image/tiff", // The MIME type
"ChargeUnits": 1.00,
"IsRead": null, //Has this fax been viewed within the GoFax Secure Web Portal (https://clientadmin.gofax.com.au)
"IsRetrieved": true //Was this fax retrieved already by an integration or GoFax Print Driver
},
..... //199 other faxes.
]
}
The response is metadata. To retrieve the actual fax document itself, send a GET request to /v1.0/ReceiveFax/{faxId}/Document where "{faxId}" is the receive ID gathered from the above response.
💡 By default, your fax will be downloaded as PDF. You can change this with the URL parameter outputType. Possible values are PDF and TIFF
This will return the base64 encoded fax document; your application will need to decode and save to file with the correct extension.
{
"Success": true,
"Message": null,
"ValidationErrors": null,
"Response": "<base64 encoded fax document>" //ASCII representation of the binary fax document
}
If you wish to use the GET /v1.0/ReceiveFaxes/UnretrievedFaxes endpoints mentioned above , we recommend that you mark the fax as retrieved after downloading the fax document.
You can do this using the PUT /v1.0/ReceiveFax/{faxId}/Retrieved endpoint, where "{faxId}" is the ID of the fax you've downloaded.
If you get the following response, you've successfully marked the fax as retrieved and it will no longer appear in GET /v1.0/ReceiveFaxes/UnretrievedFaxes.
{
"Success": true,
"Message": null,
"ValidationErrors": null,
"Response": true
}
For further details regarding any of the above REST API endpoints, please refer to our API reference (Swagger UI).