How to set up the Dropbox Fax API

Here are the steps to get the API set up and working (and optionally buy additional fax lines):

1. Send an email to support@hellosign.com containing the email address you want to use for your Dropbox Fax account. We'll write back when we've enabled Dropbox Fax API Access. 

Learn more about Dropbox Fax API prices.

2. Go to https://app.hellofax.com/account/apiInfo. Take note of your Account GUID as you'll need this for most API requests (or endpoints).

3. Make your first API request and get your account's configuration info:

curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]"

An example of this would be:

curl -u "myemail@hellofax.com:fakepassword" 
        "https://api.hellofax.com/v1/Accounts/15da1c48b10c96a903eb1bac3d592fbed24ebc35"

Another example (remember to URL encode):

curl "https://myemail%40hellofax.com:fakepassword%40api.hellofax.com/v1/Accounts/15da1c48b10c96a903eb1bac3d592fbed24ebc35"

The response will be a JSON representation of your account settings.

4. To add callback URLs for your inbound and outbound faxes again with a POST:

Note: Incoming faxes will be POST'ed to your callback URL so you don't need to retrieve them separately.

curl -u"[your username]:[your password]" \
     -d "DefaultInboundFaxCallbackUrl=https://www.example.com/inboundFax" \
     -d "DefaultOutboundFaxCallbackUrl=https://www.example.com/outboundFax" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]"

5. To review the available fax lines:

curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/FaxLines"

The response will include the FaxLine you chose when you signed up for a premium subscription.

6. To buy a fax number, we need to check which state area codes are available (not all area codes are available) with a GET:

curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/AreaCodes?StateCode=CA"

7. Buy a fax number from one of the available area codes in step 6:

curl -u "[your username]:[your password]" \
     -d "AreaCode=[area code from step 7]" \ 
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/FaxLines"

8. Now, time to send an actual fax:

curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions?To=[destination phone number]" \ 
     -F "file=@myfile.pdf"

This starts the fax sending process. Receiving a 200 HTTP response doesn’t guarantee the fax will go through, a file conversion error may occur. However, once the fax's StatusCode becomes E (for Error) or S (for Success), you’ll receive a POST to the callback URL you provided in step 4. Learn more about callback events.

Possible StatusCode values:

• T = Transmitting/sending.
• P = Pending/converting.
• S = Successfully sent.
• E = Error. Failed to convert or to send fully.
• H = On hold. This error occurs if you have an unconfirmed account or if you’re out of fax pages without a monthly subscription.

Possible ErrorCode values (reference only when StatusCode is set to E):

• B = Received a busy signal.
• N = No answer.
• A = Unallocated number (usually means it has been disconnected).
• D = The line is disconnected or unreachable.
• L = This number has been blacklisted (shouldn't happen for any US number).
• U = Unknown error. This usually occurs when a person picks up the line or an error occurred during the fax transmission.
  
  

Notes:

A. If you send a fax and the receiver's fax machine supports reading called subscriber identification (CSID), then the caller ID will display your primary fax number, or the fax number you specify in the "From" parameter. Remember, your primary fax number will appear on the fax itself. If you have multiple Dropbox Fax lines, you may choose which one to use as the sending fax machine by including the "From" parameter in the URL, for example:

curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions?To=[destination phone number]&From=[your fax line phone number]" \
     -F file=@myfile.pdf`

For the format of the "From" value, please see the "Number" field returned by calling /FaxLines (see step 5 above).

B.  You can upload multiple files and send multiple faxes in one call — just make the "file" and/or "To" parameter arrays:

curl -u "[your username]:[your password]" \
     -F file[]="@1.pdf" -F file[]="@2.txt" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions?To=[phone number in all digits]"

Or

curl -X POST https://[your username]:[your password]@api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions -F 'file[0]=@file1.pdf' \
     -F 'file[1]=@file2.pdf' \
     -F 'To[0]=[destination fax number 0]' \
     -F 'To[1]=[destination fax number 1]'

C. You can add a Dropbox Fax generated cover page by specifying one or more of the following parameters: CoverPageTo, CoverPageFrom, and CoverPageMessage.

D. Faxes sent by the API are not stored on our servers once the fax has successfully been sent — they are removed. Therefore, you cannot view them in the UI. However, incoming faxes successfully POST'ed to your callback are stored on our servers and are available to view in your "documents" screen.

E. There is a limit of 200 pending faxes per day. If you reach this limit, you'll encounter a 429 error:

Error sending fax. Status: 429; Message: Please wait. You already have at least 200 transmissions that are currently pending or transmitting.

How to check fax statuses?

curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions/[Transmission GUID]"

1. You can locate the Transmission GUID in the JSON response returned from the API call in step 8. Additionally, you can check the status of all your Transmissions by omitting the Transmission GUID:

curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions"

These results are paged. You can get different pages by specifying the Page and PageSize URL parameters. Refer to FirstPageUri, NextPageUri, PreviousPageUri, and LastPageUri response elements to of how paging works.

Notes:

• For faxes sent through the API, you won't receive an email confirmation.
• For received faxes, you may receive a notification email based on your notification settings.

2. Once the status code of the fax is set to S or E, verify that your outbound fax callback URL was triggered. It should receive a POST with a parameter called "json" that contains everything you'd get in the response to a call like you made in step 1.

If your server is down, or there are network issues, preventing a successful POST callback, Dropbox will retry the issue following this schedule after the initial attempt:

• 15 minutes
• 45 minutes
• 1 hour and 30 minutes
• 2 hours and 45 minutes
• 4 hours
• 8 hours and 15 minutes
• 16 hours and 30 minutes

During each of these retry intervals, Dropbox may attempt the POST multiple times if a 200 response code is not received.

3. If you sent the fax to your own Dropbox Fax number (useful for testing), be sure to verify that your inbound fax callback URL was also triggered.

4. List the FaxLines you have bought:

curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Account GUID]/FaxLines"

5. To delete a FaxLine, make a DELETE call to that FaxLine's Uri (specified in the response to the previous step):

curl -u "[your username]:[your password]" 
     -X DELETE "https://api.hellofax.com/v1/Accounts/[Account GUID]/FaxLines/2132935579"

If the operation is successful, you'll receive a 200 response.