How to set up the Dropbox Fax API

This article contains information on how to set up the Dropbox Fax API using the v1 endpoints, ensure it’s working, and buy additional fax lines if needed.

How to set up the Dropbox Fax API using the v1 endpoints

To get started using the v1 endpoints:

1. Send an email to support@hellosign.com containing the email address you want to use for your Dropbox Fax account. You’ll get a response once your Dropbox Fax API Access is enabled. Learn more about Dropbox Fax API prices.
2. Log in to your Dropbox Fax account. 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:

An example of this would be:

Another example (remember to URL encode):

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:

5. To review the available fax lines:

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:

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

8. To send a fax:

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 fully send.
• 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 is on the denied list (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:

• If you send a fax and the receiver's fax machine supports subscriber identification (CSID), the caller ID will display your primary fax number, or the fax number you specify in the "From" parameter. 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 the format of the "From" value, please see the "Number" field returned by calling /FaxLines (see step 5 above).

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

Or

• You can add a Dropbox Fax generated cover page by specifying one or more of the following parameters: CoverPageTo, CoverPageFrom, and CoverPageMessage.
• 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.
• There is a limit of 200 pending faxes per day. If you reach this limit, you'll encounter a 429 error:

How to check fax statuses?

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:

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.

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 (see step 1).

If a successful POST callback is prevented by a server or network issue, Dropbox will try again at these intervals:

• 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

At each interval, Dropbox may attempt the POST multiple times if a 200 response code isn't received.

3. If you sent the fax to your own Dropbox Fax number (useful for testing), verify that your inbound fax callback URL was also triggered.
4. List the FaxLines you've bought:

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

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