Faxes

Fax Subsystem Overview

The Faxes API exposes lots of ways to send, receive, track and manage faxes.

As a general concept, faxes are either considered inbound or outbound faxes. In addition:

  • API calls with the term “incoming” are used for tracking faxes currently in the process of being received
  • API calls with the term “inbox” are used for managing faxes which have already been received
  • API calls with the term “outgoing” are used for tracking faxes currently in the process of being sent
  • API calls with the term “outbox” are used for managing faxes which have already been sent

Schema

Faxes API allows you to update and access fax jobs for both sending and receiving

KeyDescriptionTypeDefaultRequiredSupport Level
attemptsThe number of attempts made, this will be set by the system and reset automatically on put/postinteger(0..4)0false
document.contentThe content provided in the body when fetching for transmission as a poststring(0..256)false
document.content_typeThe content type header to be used when fetching for transmission as a poststring()false
document.hostThe host header to be used when fetching for transmissionstring()false
document.methodThe method that should be used to retrieve the document`string(‘get''post’)`getfalse
document.refererThe referer header to be used when fetching for transmissionstring()false
document.urlThe url of the fax documentstring(7..)true
documentParameters related to the storage of a fax documentobject()false
from_nameThe sender name for the faxstring()false
from_numberThe sender number for the faxstring()true
notifications.email.send_toA list or string of email recipient(s)`array(string())string()`false
notifications.emailEmail notificationsobject()false
notifications.sms.send_toA list or string of sms recipient(s)`array(string())string()`false
notifications.smsSMS notificationsobject()false
notificationsStatus notificationsobject()false
retriesThe number of times to retryinteger(0..4)1false
subjectThe subject header in an email to fax messagestring()false
to_nameThe recipient name for the faxstring()false
to_numberThe recipient number for the faxstring()true
tx_result.error_messageA description of any error that occurredstring()""false
tx_result.fax_bad_rowsThe number of bad rowsinteger()0false
tx_result.fax_error_correctionTrue if fax error correction was usedboolean()falsefalse
tx_result.fax_receiver_idThe receiver id reported by the remote fax devicestring()""false
tx_result.fax_speedThe speed (Baud-Rate) achieved during transmissioninteger()0false
tx_result.pages_sentThe number of pages transmittedinteger()0false
tx_result.successTrue if the fax transmission was successfulboolean()falsefalse
tx_result.time_elapsedThe amount of time from submission to completioninteger()0false
tx_resultThe result of a transmission attemptobject()false

Send Outgoing Fax

There are two way to send outgoing fax. You can provide a URL to the document you wish or send or you can provide the the document with the same send request payload.

PUT /v2/accounts/{ACCOUNT_ID}/faxes

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"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes
{
    "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 use a single PUT request and send a multi-part content-type to attach both the JSON metadata about the fax transmission and the document itself, in a single request. This avoids needing to have an external storage location for storing fax attachments prior to processing. This is a good solution for portals that upload documents.

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}' \
     http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes

Create an outgoing fax (Alias)

This is identical to the PUT /faxes above.

PUT /v2/accounts/{ACCOUNT_ID}/faxes/outgoing

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/outgoing

Fetch outgoing faxes and their statuses

This API retrieves a listing of all outgoing faxes. Use the “id” to fetch details about a particular job. Results will contain a listing of both API- and SMTP (email) - initiated outbound faxes.

GET /v2/accounts/{ACCOUNT_ID}/faxes/outgoing

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/outgoing
{
    "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"
}

Fetch details of a queued outgoing fax job

Get all the details about a fax that is in the outgoing queue.

GET /v2/accounts/{ACCOUNT_ID}/faxes/outgoing/{FAX_JOB_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/outgoing/{FAX_JOB_ID}
{
    "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"
}

Managing Past Outbound Faxes

Fetch 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. Results will contain a listing of both API- and SMTP (email) - initiated outbound faxes.

GET /v2/accounts/{ACCOUNT_ID}/faxes/outbox

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/outbox

Fetch A Fax From The Outbox Folder

GET /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}

Resubmit A Fax From The Outbox Folder

PUT /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"action": "resubmit", "data": {}}'
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}

Fetch The Fax Payload

Fetch the fax in outbox.

GET /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}/attachment

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}/attachment

Downloading vs viewing the payload

How the attachment is fetched can be controlled by the Content-Disposition response header. If Content-Disposition: inline the content fetched will typically be viewed in the web browser (or whatever client is fetching the data). Content-Disposition: attachment will cause most clients to offer a download/‘Save as’ dialog.

The client request can control the response’s Content-Disposition by setting disposition on the querystring:

GET /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}/attachment?disposition=attachment

attachment is the default response disposition.

If a fax job was queued or attempted to be queued as the result of an inbound email, the SMTP log for that fax can be retrieved via this API. This is also useful for helping debug problems with inbound faxes, such as when the domain matched an account for an inbound fax, but not a specific faxbox, and thus failed to process.

GET /v2/accounts/{ACCOUNT_ID}/faxes/smtplog

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/smtplog

GET /v2/accounts/{ACCOUNT_ID}/faxes/smtplog/{ATTEMPT_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/smtplog/{ATTEMPT_ID}

Remove A Fax From The Outbox Folder

This API allows you to delete an old fax message. For privacy reasons, this may be useful if you wish to remove all evidence of a previously sent outbound fax.

DELETE /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}

Remove The Fax Payload

In some cases, you may wish to remove the document from a fax (usually for privacy reasons) but keep evidence that the fax transmission occurred. This will remove attachments but not the metadata from a sent fax.

DELETE /v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}/attachment

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/outbox/{FAX_ID}/attachment

Managing Past Inbound Faxes

Fetch All Faxes In The Inbox Folder

Retrieve a list of faxes that have previously been received.

GET /v2/accounts/{ACCOUNT_ID}/faxes/inbox

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/inbox

Fetch A Fax From The Inbox Folder

Retrieve all metadata about a particular fax for which you have the fax ID.

GET /v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}

Fetch The Fax Payload

GET /v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}/attachment

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}/attachment

See the outbox equivalent above for instructions on setting the disposition of the response for download vs viewing of the attachment.

Remove A Fax From The Inbox Folder

Delete an old fax message. For privacy reasons, this may be useful if you wish to remove all evidence of a previously received inbound fax.

DELETE /v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}

Remove The Fax Payload

In some cases, you may wish to remove the document from a fax (usually for privacy reasons) but keep evidence that the fax receipt occurred. This will remove attachments but not the metadata from a received fax. Useful after you’ve done post-processing on a fax externally.

DELETE /v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}/attachment

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/inbox/{FAX_ID}/attachment

APIs under active development

Receiving Inbound Faxes

List Incoming Fax Jobs

Retrieve a list of faxes that are currently being received or attempted to be received. NOTE: THIS FUNCTION DOES NOT WORK YET AS OF THE WRITING OF THIS DOCUMENT. We’ll update this doc once this function is complete.

GET /v2/accounts/{ACCOUNT_ID}/faxes/incoming

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/incoming
Fetch An Incoming Fax Job

GET /v2/accounts/{ACCOUNT_ID}/faxes/incoming/{FAX_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/faxes/incoming/{FAX_ID}

On this page