Dropbox Fax API v3

This guide is for Dropbox Fax API developers currently using the v1 endpoints who want to learn about the changes between v1 and v3.

Notable changes

Authentication matches the API Key method used by the Dropbox Sign API
API requests that require payment can enable test mode
API subscription will be billed automatically to the credit card on file
API requests can be reviewed on the API Dashboard

Corresponding Endpoints

Endpoint	v1	v3
Send Fax	POST /v1/Accounts/[ACCOUNT GUID]/Transmissions	POST /v3/fax/send
Get Fax	GET /v1/Accounts/[ACCOUNT GUID]/Transmissions/[TRANSMISSION GUID]	GET /v3/fax
List All Faxes	GET /v1/Accounts/[ACCOUNT GUID]/Transmissions	GET /v3/fax/list
List Available Area Codes	GET /v1/AreaCodes	GET v3/fax_line/area_codes
Purchase Fax Line	POST /v1/Accounts/[ACCOUNT GUID]/FaxLine	POST v3/fax_line/create
List Fax Lines	GET /v1/Accounts/[ACCOUNT GUID]/FaxLine	GET v3/fax_line/list
Delete Fax Line	DELETE /v1/Accounts/[Account GUID]/FaxLines/[PHONE NUMBER]	DELETE v3/fax_line/delete

Additional Functionality

New endpoints are available in v3 to allow for more flexibility with faxes and fax lines.

Endpoint	v3
Download Fax Files	POST /v3/fax/files/[FAX ID]
Delete Fax	DELETE /v3/fax/[FAX ID]
Get Fax Line	GET /v3/fax_line/
Add User to Fax Line	PUT /v3/fax_line/add_user
Remove Fax Line Access	PUT /v3/fax_line/remove_user

Callbacks

Inbound and outbound fax callbacks will continue to be POSTed to the set DefaultInboundFaxCallbackUrl and DefaultOutboundFaxCallbackUrl. Callbacks to these URLs will remain in the v1 format.

The updated structure will be POSTed to the v3 callback url settings that can be specified on the API Settings page. These new settings have the same expectations as the Sign API and require the same response detailed in the Events and Callbacks Walkthrough.

Example v3 Payload

Copy

Copied

    {
      "transmission": {
        "test_mode": false,
        "signature_request_id": "",
        "title": "Example Title",
        "original_title": "Example Title",
        "message": "Please read",
        "metadata": {},
        "created_at": 1738001529,
        "is_complete": false,
        "is_declined": false,
        "has_error": false,
        "files_url": "https://api.hellosign.com/apiapp_dev.php/v3/fax/files/9c2c7e8c2ed1839f75a9a0227ce2954b1d7c3407",
        "cc_email_addresses": [],
        "final_copy_uri": "/v3/transmission/final_copy/9c2c7e8c2ed1839f75a9a0227ce2954b1d7c3407",
        "template_ids": [],
        "custom_fields": [],
        "attachments": [],
        "response_data": [],
        "signatures": []
      },
      "event": {
        "event_time": "1738001529",
        "event_type": "fax_sent",
        "event_hash": "950d3bdf03a30d520dfa6ac51a952ff93fe3a4d9754dd1412b6aec36206c1e81",
        "event_metadata": {
          "reported_for_account_id": "63522885f9261e2b04eea043933ee7313eb674fd"
        }
      },
      "account_guid": "63522885f9261e2b04eea043933ee7313eb674fd",
      "account_id": null,
      "client_id": null
    }

Event Names

Here is a list of webhook events that can be sent to your Fax callback urls:

Event type	Description
`fax_received`	An inbound fax was received
`fax_sent`	The outbound fax was sent successfully
`fax_on_hold`	The outbound fax was placed on hold
`fax_busy`	The outbound fax received a busy signal from the recipient's fax line
`fax_no_answer`	The outbound fax recipient fax line did not pick up
`fax_disconnected`	The outbound fax recipient fax line disconnected before the fax was sent
`fax_blacklisted`	The outbound fax recipient fax line is blocked or invalid

Data

Faxes sent via the v1 API are not stored once the fax has been sent successfully and are unable to be viewed in the UI. Incoming faxes that are POSTed to your callback URL are available in the "Faxes" page. Using the v3 API, this setting can now be enabled or disabled on the API Settings page.

Backwards compatability

If you move to the new API Core subscription plan, you will be billed automatically at the end of the billing month based on your fax usage and number of additional fax lines. Users on the new API Core plan can access both the v1 and v3 endpoints. Users on the existing API Basic plan can only access the v1 endpoints.