How can I send a fax using API?

Updated March 19, 2024 15:26

Who can use this feature?

Available on Enterprise plan.

All members.

To send a fax using the API, you first need to upload your required files, followed by the preparing those files for faxing and scheduling their transmission.

Once your fax is scheduled, you can implement an HTTP server and leverage a webhook mechanism. This approach ensures that an HTTP message is dispatched both upon successful fax transmission and in the event of transmission failure.

Note: Make sure that you have completed the initial authentication process, and successfully logged in to the API. For additional instructions, refer to our guide here.

Step 1: Upload files to be faxed

To upload a file, initiate an HTTP POST request to the following URL: https://restapi.fax.plus/v3/accounts/[user ID]/files?format=[file format, 'pdf' or 'tiff']

Make sure to include the following headers in your request:

- Content-Type:
```
multipart/form-data
```

- Authorization:
```
Bearer [access token]
```

- x-fax-clientid:
```
[client ID]
```

For the body:

{
  "fax_file": [file]
}

‍

In the following example, "self" is utilized as the user ID to represent the currently logged-in user's unique identification:

FAX.PLUS-Send-Fax-API-2.png

FAX.PLUS-Send-Fax-API-3.png

Once the file has been successfully uploaded, you will receive a path leading to the temporary location of the file on Fax.Plus.

Step 2: Send a fax using API

Once the uploads are completed, you can begin preparing your fax for sending. To initiate the process, perform an HTTP POST request to the following URL:
https://restapi.fax.plus/v3/accounts/[user ID]/outbox

Make sure to include the following headers in your request:

- Authorization:
```
Bearer [access token]
```
- x-fax-clientid:
```
[client ID]
```

For the request body:

{
"from": "",
"to": [
""
],
"files": [
""
],
"comment": {
"text": ""
},
"send_time": "",
}

FAX.PLUS-Send-Fax-API-4.png

Upon successful scheduling of the fax, you will be provided with an Outbox ID. This ID can be utilized to make modifications or delete the fax before it is actually sent.

Note: Faxes are associated with multiple IDs with our API. This design is in place because fax transmission operates asynchronously. Specifically, an outgoing fax will be identified by two distinct IDs: Outbox ID, which serves its purpose until the fax is successfully sent, and Fax ID, which becomes the definitive identifier for the fax once it has been successfully transmitted.

Step 3: Use webhooks to check the status of your sent fax

After scheduling the fax, you can monitor its status by reviewing the list of faxes located in the outbox or the sent category.

Alternatively, you have the option to establish an HTTP server and use a webhook. This will trigger an HTTP message to be sent when the fax is successfully sent or if there's a failure in sending.

Follow these steps to set up the Webhook:

Login to your Fax.Plus account, and go the Profile section on your Dashboard.
Under the tab for Integrations, find the box for Web Hooks.
Find Incoming Faxes and Incoming Faxes. Click on Manage to modify the Webhook.

Once you have set up the Webhook, you will receive the following notification once an outgoing fax has been processed:

{
"hook": {
"id": "",
"event": "fax_sent",
"event_time": "2022-12-09 15:50:00",
"target": "http://www.example.com/callback/fax_sent"
},
"data": {
"id": "",
"pages": 1,
"from": "",
"to": "",
"start_time": "2022-12-09 15:50:00",
"file": "",
"file_name": "fax-from-1xxxxxxxxxxxx",
"cost": 1,
"status": "success"
}
}

This message will provide you with the transmission time, indicate the success of the fax transmission (via the "status" field), and furnish you with the unique fax ID. This fax ID can be utilized to retrieve the fax file or obtain a fax confirmation report.

Need Support?