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

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

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}

Faxes API

API calls

Parameters

Create an outgoing fax

Create an outgoing fax (alias)

Get outgoing faxes and their statuses

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 from the outbox

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 from the inbox

Get an incoming fax job