To send a fax via the API, you first need to upload the files and then prepare the uploaded files to fax and schedule them for transmission. Once the fax is scheduled, you can implement a HTTP server and use a webhook, so that a HTTP message is sent when the fax is sent, or failed to be sent.
<span class="info">Make sure you have already setup the initial authentication flow and logged in on the API. Learn more</span>
To upload a file, do a HTTP POST to <span class="code">https://restapi.fax.plus/v3/accounts/[user ID]/files?format=[file format, 'pdf' or 'tiff']</span>
with the following headers:
and for the body:
<span class="code-long"> {
</br> "fax_file": [file]
</br>}</span>
In the following example, <span class="code">self</span> is used as the user ID, so that the user ID is the one of our logged-in user.
If the file was successfully uploaded, a path is returned, pointing to the FAX.PLUS (temporary) location of the file.
After the uploads are done, the fax can be prepared for sending.
To get started, do a HTTP POST to <span class="code">https://restapi.fax.plus/v3/accounts/[user ID]/outbox</span>
with the following headers:
and for the body:
<span class="code-long"> {
</br> "from": "<number used to send the fax, assigned to the user>",
</br> "to": [
</br> "<destination number>"
</br> ],
</br> "files": [
</br> "<path returned by the uploaded file>"
</br> ],
</br> "comment": {
</br> "text": "<optional comment>"
</br> },
</br> "send_time": "<timestamp for the fax to be sent>",
</br>}</span>
If the fax is successfully scheduled, you will receive an outbox ID: you can use it to modify or delete it before the fax is sent.
<span class="info">Faxes have multiple IDs in our API. The reason for this is that sending a fax is an asynchronous process, with multiple retries if needed (line is busy, etc.)
</br>An outgoing fax will have 2 IDs:
</br>• the outbox ID, used only until the fax is not sent,
</br>• the fax ID, representing the fax once it is sent.</span>
Once the fax is scheduled, you can check the status by going through the list of faxes in the outbox, or the list of faxes in the sent category.
Alternatively, you can implement a HTTP server and use a webhook, so that a HTTP message is sent when the fax is sent, or failed to be sent.
To set up the Webhook:
After you setup Webhook, you will receive the following message once an outgoing fax is processed:
<span class="code-long"> {
</br> "hook": {
</br> "id": "<fax ID>",
</br> "event": "fax_sent",
</br> "event_time": "2022-12-09 15:50:00",
</br> "target": "http://www.example.com/callback/fax_sent"
</br> },
</br> "data": {
</br> "id": "<fax ID>",
</br> "pages": 1,
</br> "from": "<source phone number>",
</br> "to": "<destination phone number>",
</br> "start_time": "2022-12-09 15:50:00",
</br> "file": "<filename>",
</br> "file_name": "fax-from-1xxxxxxxxxxxx",
</br> "cost": 1,
</br> "status": "success"
</br> }
</br>}</span>
This message will give you the time of transmission, if the fax was sent successfully (<span class="code">status</span> field) and the fax ID that can be used to retrieve the fax file, or get a fax confirmation report.
