Complete walkthrough for setting up The Dropbox Fax API

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

1. Sign up for any paid account at https://app.hellofax.com/info/pricing, then send an email message to support@hellosign.com containing the email address 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: Learn more about 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 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. Let's review the available fax lines.

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 you signed up for a premium subscription.

6. Now, let's purchase a fax number. First, 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. Purchase 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 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 above).

B.  You can upload multiple files and/or send multiple faxes in one call - just make the "file" and/or "To" parameters 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 cover page by entering 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, you cannot view them in the UI. However, incoming faxes that are successfully POST'ed to your callback are stored on our servers and are available in your "documents" screen.

E. There is a rate limit of 200 pending faxes per day. 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 above:

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

You can find the Transmission GUID in the JSON response returned from the API call in step 8. You can also 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. See the FirstPageUri, NextPageUri, PreviousPageUri, and LastPageUri response elements to get a better idea of how the 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 depending on your notification settings.

10. After the status code of the fax is set to S or E, 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'll 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 we may 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 (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.