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

Inbound fax operations

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}