Faxes API
The faxes API exposes several ways to send, receive, track, and manage faxes over email. Use the Faxes API to update and access inbound and outbound fax jobs.
NOTE: As a general concept, faxes are either considered inbound or outbound.
API calls
Click on each call to view the endpoint, method, and request example.
Outbound fax operations
- Create an outgoing fax
- Create an outgoing fax alias
- Get outgoing fax status
- Get details of a queued outgoing fax job
- Get historic outbound faxes
- Get a fax from the outbox folder
- Resubmit a fax from the outbox folder
- Get the fax payload
- Get logs related to outbound faxes submitted through email
- Get a specific log related to email
- Remove a fax from the outbox folder
- Remove the fax payload
Inbound fax operations
- Get all faxes in the inbox folder
- Get a fax from the inbox folder
- Get the fax payload
- Remove a fax from the inbox folder
- Remove the fax payload
- Get an incoming fax job
NOTE:
- API calls labeled "incoming" are used for tracking faxes currently in the process of being received.
- API calls labeled "inbox" are used for managing faxes which have already been received.
- API calls labeled "outgoing" are used for tracking faxes currently in the process of being sent.
- API calls labeled "outbox" are used for managing faxes which have already been sent.
Parameters
The table shows the possible parameters available for fax requests.
Key | Description | Type | Options/Min/Max/Default |
---|---|---|---|
document.url |
Required. The URL of the fax document. | string | |
from_number |
Required. The sender number for the fax. | string | |
to_number |
Required. The recipient number for the fax. | string | |
attempts |
The number of attempts made, this is set by the system and reset automatically after PUT or POST. | integer | |
document |
Parameters related to the storage of a fax document. | object | |
document.content |
The content provided in the body when fetching for transmission as a POST. | string | (0..256) |
document.content_type |
The content type header to be used when fetching for transmission as a POST. | string | |
document.host |
The host header to be used when fetching for transmission. | string | |
document.method |
The method that should be used to retrieve the document. | string | get , post . The default is get . |
document.referer |
The referer header to be used when fetching for transmission. | string | |
notifications |
Status notifications. | object | |
notifications.email |
Email notifications. | object | |
notifications.email.send_to |
A list or string of email recipents. | string, array | |
notifications.sms |
SMS notifications. | object | |
notifications.sms.send_to |
A list or string of SMS recipents. | string, array | |
retries |
The number of times to retry. | integer | The default is 1 . |
to_name |
The recipient name for the fax. | string | |
tx_result |
The result of a transmission attempt. | object | |
tx_result.error_message |
A description of any error that occurred. | string | |
tx_result.fax_bad_rows |
The number of bad rows. | integer | |
tx_result.fax_error_correction |
This parameter returns true if fax error correction was used. |
boolean | |
tx_result.fax_receiver_id |
The receiver ID reported by the remote fax device. | string | |
tx_result.fax_speed |
The speed (baud-rate) achieved during transmission. | integer | |
tx_result.pages_sent |
The number of pages that were transmitted. | integer | |
tx_result.success |
This parameter returns true if the fax transmission was successful. |
boolean | The default is false . |
tx_result.time_elapsed |
The amount of time between fax submission and completion. | integer | The default is 0 . |
tx_result |
The result of a transmission attempt. | object |
Processing States
State | Description |
---|---|
attaching_files |
A fax job with a multipart or related content type was submitted through the API or SMTP (email), and the system is in the process of attaching the files to the fax job. |
pending |
The fax is waiting to be picked up by the fax sending job. |
failed |
If the fax document cannot be retrieved through a requests URL, the state is failed and the error text contains "could not retrieve file, HTTP response XXX". |
processing |
The fax is actively picked up by the fax worker and are being processed |
completed |
The fax is finished sending. |
failed |
The fax did not successfully send after all allotted retries. The FreeSWITCH error code is returned in this case. |
Create an outgoing fax
Creates an outgoing fax. There are two ways to create a fax depending on how you want to attach the fax file for processing:
In the first method, you can create a fax document that includes a URL. The fax document is fetched by the fax_jobs
worker and distributed to fax_worker
processes. You can fetch the status of the created job using the faxes/outgoing/{FAX_ID}
API.
Method and endpoint
PUT /v2/accounts/{ACCOUNT_ID}/faxes
Request
curl -v -X PUT \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-d '{"data":{"document":{"url":"http://myserver.com/fax.pdf","method":"get"},"retries":3,"from_name":"Test Fax","from_number":"18884732963","to_name":"To Name","to_number":"18884732963"}}' \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes
Response
{
"data":{
"document":{
"url":"http://myserver.com/fax.pdf",
"method":"get"
},
"retries":3,
"from_name":"Test Fax",
"from_number":"18884732963",
"to_name":"To Name",
"to_number":"18884732963",
"attempts":0,
"tx_result":{
"error_message":"",
"fax_bad_rows":0,
"fax_error_correction":false,
"fax_receiver_id":""
,"fax_speed":0,
"pages_sent":0,
"success":false,
"time_elapsed":0
},
"fax_timezone":"undefined",
"id":"{FAX_JOB_ID}"
},
"revision":"{REVISION}",
"request_id":"{REQUEST_ID}",
"status":"success",
"auth_token":"{AUTH_TOKEN}"
}
In the second method, you can send a multipart content-type that contains both the document itself and the JSON metadata about the fax transmission. You can send it in a single PUT request. This method means that you don't need an external storage location for storing fax attachments prior to processing. It is a good solution for systems such as portals that are used for uploading documents.
Request
curl -v -X PUT \
-H "Content-Type: multipart/mixed" \
-F "content=@fax.json; type=application/json" \
-F "content=@fax.pdf; type=application/pdf" \
-H 'X-Auth-Token: {AUTH_TOKEN}' \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes
Create an outgoing fax (alias)
This is identical to the PUT faxes above.
Method and endpoint
PUT /v2/accounts/{ACCOUNT_ID}/faxes/outgoing
Request
curl -v -X PUT \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/outgoing
Get outgoing faxes and their statuses
Retrieves a listing of all outgoing faxes. Use the id
to fetch details about a particular job. The results contain a listing of both API-initiated and SMTP-initiated (email) outbound faxes.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/outgoing
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/outgoing
Response
{
"auth_token": "{AUTH_TOKEN}",
"data": [
{
"created": 63626410973,
"from": "18884732963",
"id": "{FAX_JOB_ID}",
"status": "pending",
"to": "18884732963"
}
],
"page_size": 1,
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"start_key": [
"{START_KEY}"
],
"status": "success"
}
Get details of a queued outgoing fax job
Returns the details of a fax that is in the outgoing queue.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/outgoing/{FAX_JOB_ID}
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/outgoing/{FAX_JOB_ID}
Response
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"attempts": 0,
"created": 63626410973,
"delivered": "undefined",
"document": {
"method": "get",
"url": "http://myserver.com/fax.pdf"
},
"fax_timezone": "undefined",
"from_name": "Test Fax",
"from_number": "18884732963",
"id": "{FAX_JOB_ID}",
"retries": 3,
"status": "pending",
"to_name": "To Name",
"to_number": "18884732963",
"tx_result": {
"error_message": "",
"fax_bad_rows": 0,
"fax_error_correction": false,
"fax_receiver_id": "",
"fax_speed": 0,
"pages_sent": 0,
"success": false,
"time_elapsed": 0
}
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Get historic outbound faxes
Returns all previously sent faxes in the outbox folder. This API retrieves a listing of all outgoing faxes which have already been sent or attempted and are no longer in queue. The results contain a listing of both API-initiated and SMTP-initiated outbound faxes.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/outbox
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/outbox
Get a fax from the outbox folder
Retrieves a specific fax from the outbox folder.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}
Resubmit a fax from the outbox folder
Resends a fax from the outbox folder.
Method and endpoint
PUT /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}
Request
curl -v -X PUT \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-d '{"action": "resubmit", "data": {}}'
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}
Get the fax payload
Returns the fax payload.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}/attachment
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}/attachment
Get logs related to outbound faxes submitted through email
Retrieves the SMTP log for any fax job that was queued or was attempted to be queued as the result of an inbound email. This result is useful for helping debug problems with inbound faxes. For example, if the domain matched an account for an inbound fax, but not a specific faxbox, and failed to process.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/smtplog
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/smtplog
Get a specific log related to email
Retrieves a specific SMTP log for a fax that was delivered through email.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/smtplog/{ATTEMPT_ID}
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/smtplog/{ATTEMPT_ID}
Remove a fax from the outbox folder
Deletes an old fax message. This request is useful if you wish to remove all evidence of a previously sent outbound fax.
Method and endpoint
DELETE /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}
Request
curl -v -X DELETE \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}
Remove the fax payload from the outbox
Removes attachments but keeps the metadata related to the sent fax. In some cases, you might want to remove the document from a fax (usually for privacy reasons), but keep evidence that the fax transmission occurred.
Method and endpoint
DELETE /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}/attachment
Request
curl -v -X DELETE \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}/attachment
Get all faxes in the inbox folder
Returns a list of faxes that have previously been received.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/inbox
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/inbox
Get a fax from the inbox folder
Returns all metadata about a particular fax using the fax ID.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}
Get the fax payload
Returns the fax document and attachments for a particular inbound fax using the fax ID.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}/attachment
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}/attachment
Remove a fax from the inbox folder
Deletes an old fax message. You can remove all evidence of a previously received inbound fax.
Method and endpoint
DELETE /v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}
Request
curl -v -X DELETE \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}
Remove the fax payload from the inbox
Removes attachments but keeps the metadata from a received fax. If you want to remove the document for privacy but keep the evidence that the fax was received.
Method and endpoint
DELETE /v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}/attachment
Request
curl -v -X DELETE \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}/attachment
Get an incoming fax job
Returns details of the incoming fax job.
Method and endpoint
GET /v2/accounts/{ACCOUNT_ID}/faxes/incoming/{FAX_ID}
Request
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/faxes/incoming/{FAX_ID}