Complete Walkthrough for Setting Up The Dropbox Fax API

Here are the steps to get the API setup and working (and optionally purchase additional fax lines):

1. Sign up for any paid account at https://app.hellofax.com/info/pricing, then write in to support@hellosign.com with the email address that you used to sign up for the Dropbox Fax account. We'll write back when we've enabled Dropbox Fax API Access. This will switch your plan from the hellofax.com one to the Dropbox Fax API.

NOTE: Click HERE for the Dropbox Fax API subscription costs.

2. Go to https://app.hellofax.com/account/apiInfo and take note of your Account GUID. You'll need this for most API requests.

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]"

One example of this would be:

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

Another example (remember to url encode!) would be:

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

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

4. Let's 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 there is no need to retrieve them via a separate action.

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. Let's see what fax lines we have at our disposal:

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

The response should contain the FaxLine you selected when signing up for a premium subscription.

6. Let's purchase a fax number. First, we need to see what area codes are available in our state (not all area codes are available) with a GET:

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

7. Purchase a fax line 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 let's actually send a 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 will begin the process of sending the fax. Just because you get a 200 HTTP response to this call does not mean that the fax will go through or even be sent (a file conversion error could occur). However, once the fax's StatusCode becomes E (for Error) or S (for Success) you will get a POST back to the callback URL you specified in step #4. Click here for an example of the callback event body.

Possible StatusCode values:

T = transmitting/sending
P = pending/converting
S = successfully sent
E = error. Failed to convert or to send fully
H = on hold. A type of error caused by having an unconfirmed account or by being out of fax pages and not having 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 human answers 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 CSID, then the caller ID will display your primary fax number (or the fax number you specify in the ‘From’ parameter). (Fax machines supporting CSID is a standard: http://en.wikipedia.org/wiki/Called_subscriber_identification) Also, keep in mind that your primary fax number will be overlaid on the fax itself. If you have multiple Dropbox Fax fax lines, you may specify which one to use as the sending fax machine by including the 'From' parameter in the URL, e.g.:

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)

B.  You can upload multiple files and/or send multiple faxes in one call - just make the `file` and/or `To` params each an array:

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 coverpage by supplying one or more of the following parameters: CoverPageTo, CoverPageFrom, and CoverPageMessage

D. Faxes sent via the API are not stored on our servers once the fax has successfully been sent - they are removed. Therefore they are not available to be viewed in our UI. However incoming faxes which are successfully POST'ed to your callback are stored on our servers and are available in your "documents" screen. It's only outgoing faxes (from the API) that we delete and do not make available in the UI.

E. There is a 200 Pending Faxes in the prior day rate limit. If you hit the limit, you'll receive this 429 error:

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

9. Check the status of the fax you initiated in step #8:

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

The Transmission GUID can be found in the JSON response returned from the API call in step #9. If you want, 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"

Note that these results are paged. You can get different pages by specifying the Page and PageSize url parameters. See the FirstPageUri, NextPageUri, PreviousPageUri, and LastPageUri response elements to get a better idea of how the paging works.

NOTE: For faxes sent through the API, you will never receive an email confirmation. For received faxes, you may receive a notification email depending on your setting for notifications, which is configurable at https://www.hellofax.com/home/myAccount

10. After the status code of the fax gets set to S or E you'll also want to verify that your outbound fax callback URL was hit. 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 #9.

If your server is down, or there are network issues, and the POST callback cannot be successfully made, we will issue retries. Seven retries will be attempted before giving up. Here is the retry schedule (in time since the initial callback was attempted):

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

Please note that during each of these retry intervals we may in fact attempt the POST multiple times (if we do not receive a 200 response code).

11. If you happened to send the fax to your own Dropbox Fax fax number (silly in real life, but useful for testing), you should also verify that your inbound fax callback URL was hit as well.

12. Let's list the FaxLines you have purchased:

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

13. 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 was successful, you should receive a 200 response.

NOTES:

- There is currently a bug where the JSON contained in the callbacks contains a "Transaction" instead of a "Transmission". This is just a typo and will be fixed in the next version of the API.