API Documentation

Introduction

In these series of articles, you'll find detailed guides on setting up some of the most common use cases for integrating HumbleFax into your applications and services.

The HumbleFax API is organized around REST. Our API has resource-oriented URLs, supports HTTP Verbs, and responds with HTTP Status Codes. All API requests and responses, including errors, will be represented as JSON.

All successful requests are replied with a 200 OK HTTP status code.

Our API is under continuous development, so please check back often for changes and additions.

Potential Error Codes

Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.

If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.

Rate Limits

If you exceed the rate limits below, your ip address will be blocked for 60 seconds.

Per second 5 requests

Authentication

The HumbleFax API makes use of HTTP Basic Authentication.

Creating an API login and password is simple. Head over to the API / Developer section in the dashboard. Generate your keys by selecting the "New Keys" icon on the top of the page. For API requests, your login is your API Access Key and the password is the API Secret Key.

Sending Curl Request with Basic Authentication Credentials

To send basic auth credentials with Curl, use the "-u login: password" command-line option. Curl automatically converts the login: password pair into a Base64-encoded string and adds the "Authorization: Basic [token]" header to the request.

API Access Key This serves as your API username
API Secret Key This serves as your API password

In this Curl request with Basic Auth Credentials example, we send a request with basic authorization credentials to the SendFax HumbleFax API URL.

curl https://api.humblefax.com/fax/12345/send -u "accessKey:secretKey"

Tutorial: Send a Fax

The following section is a brief tutorial on how to send a fax using the HumbleFax API.

Steps

Signup and Retrieve your API credentials

Sign up for your HumbleFax account. Head over to the API / Developer section to create your API credentials.

Once your credentials are created, you can use the following information in all subsequent API requests to the HumbleFax endpoints:

API Access Key This serves as your API username
API Secret Key This serves as your API password

Tips

To avoid errors, make sure to:

Request via Postman

Postman is a highly intuitive GUI platform that lets you build API requests very quickly. Download it for free here. Postman also has a very useful tutorial on how to send your HTTP requests.

  1. In the URL tab, copy and paste the HTTP portion of your cURL request above.
  2. In the Authorization tab, do the following:
    • Select Basic Auth for the Type.
    • Enter your accessKey in the username field, and your secretKey in the password field.
  3. Hit Send

Create a Temporary Fax

The first step is to create a temporary fax object. Supply all the metadata for the fax including recipients and coversheet info if applicable. See the CreateTmpFax endpoint for more options.

curl -L 'https://api.humblefax.com/tmpFax' \
     -H 'Content-Type: application/json' \
     -u "accessKey:secretKey" \
     -d '{
         "toName": "John Q. Public",
         "fromName": "Jane Q. Public",
         "subject": "This is a test fax",
         "message": "Is your refrigerator running?",
         "companyInfo": "Amalgamated Faxing Co",
         "fromNumber": 12123334444,
         "recipients": [
             16462254444,
             12014443333
         ],
         "resolution": "Fine",
         "pageSize": "Letter",
         "scheduledTime": 1696047273,
         "includeCoversheet": true,
         "uuid": "ABC-123"
     }'

In the JSON response from the server, note the tmpFaxId for future requests.

{
    "data": {
        "tmpFax": {
            "id": "673ec38414d6d0.55271817",
            "toName": "John Q. Public",
            "fromName": "Jane Q. Public",
            "subject": "This is a test fax",
            "message": "Is your refrigerator running?",
            "companyInfo": "Amalgamated Faxing Co",
            "fromNumber": 12123334444,
            "recipients": [
                16462254444,
                12014443333
            ],
            "resolution": "Fine",
            "pageSize": "Letter",
            "scheduledTime": 1732166532,
            "includeCoversheet": true,
            "uuid": "ABC-123",
            "tmpAttachments": [
                {
                    "id": "673ec38414d707.66599643",
                    "fileName": "test.docx",
                    "hash": "d41d8cd98f00b204e9800998ecf8427e",
                    "numPages": 32,
                    "fileSize": 21321
                }
            ],
            "numPages": 33
        }
    }
}

Upload Attachment(s)

Next, upload your attachment(s), one by one, using the CreateAttachment endpoint. Note that each time you upload an attachment, the HumbleFax backend system uses a queueing system to validate each file, so allow an appropriate amount of time to wait for the server response. Most of the time this will be under five seconds, but occasionally during peak hours for long documents the response time could be up to a minute.

This step is optional if you are sending a coversheet.

curl -L 'https://api.humblefax.com/attachment/651b17fab46c18.89226873' \
     -u "accessKey:secretKey" \
     -F 'test.docx=@"/tmp/docs/test.docx"

Send the Temporary Fax

A simple POST request to the SendTmpFax endpoint instructs the server to convert the temporary fax into a sentFax object, and send it to the fax queue.

curl -L 'https://api.humblefax.com/tmpFax/651b17fab46c18.89226873/send' \
     -u "accessKey:secretKey"

Congratulations, you sent your first fax with the HumbleFax API. We can't wait to see what you do with these tools!