# Fax

> A guide to assist customers migrating from v1 to v3 of the Fax API

# 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.

<BlueBox>
  <b>
    Notable changes
  </b>

  <br />

  <ul>
    <li>
      Authentication matches the API Key method used by the 

      [Dropbox Sign API](/api/api-reference-authentication)
    </li>

    <li>
      API requests that require payment can enable test mode
    </li>

    <li>
      API subscription will be billed automatically to the credit card on file
    </li>

    <li>
      API requests can be reviewed on the 

      [API Dashboard](/docs/guides/api-dashboard)
    </li>
  </ul>
</BlueBox>

## Corresponding Endpoints

<table>
  <thead>
    <th>
      Endpoint
    </th>

    <th>
      v1
    </th>

    <th>
      v3
    </th>
  </thead>

  <tbody>
    <tr>
      <td>
        Send Fax
      </td>

      <td>
        POST /v1/Accounts/[ACCOUNT GUID]/Transmissions
      </td>

      <td>
        POST 

        [/v3/fax/send](/api/fax/send)
      </td>
    </tr>

    <tr>
      <td>
        Get Fax
      </td>

      <td>
        GET /v1/Accounts/[ACCOUNT GUID]/Transmissions/[TRANSMISSION GUID]
      </td>

      <td>
        GET 

        [/v3/fax](/api/fax/get)
      </td>
    </tr>

    <tr>
      <td>
        List All Faxes
      </td>

      <td>
        GET /v1/Accounts/[ACCOUNT GUID]/Transmissions
      </td>

      <td>
        GET 

        [/v3/fax/list](/api/fax/list)
      </td>
    </tr>

    <tr>
      <td>
        List Available Area Codes
      </td>

      <td>
        GET /v1/AreaCodes
      </td>

      <td>
        GET 

        [/v3/fax_line/area_codes](/api/fax-line/area-code-get)
      </td>
    </tr>

    <tr>
      <td>
        Purchase Fax Line
      </td>

      <td>
        POST /v1/Accounts/[ACCOUNT GUID]/FaxLine
      </td>

      <td>
        POST 

        [/v3/fax_line/create](/api/fax-line/create)
      </td>
    </tr>

    <tr>
      <td>
        List Fax Lines
      </td>

      <td>
        GET /v1/Accounts/[ACCOUNT GUID]/FaxLine
      </td>

      <td>
        GET 

        [/v3/fax_line/list](/api/fax-line/list)
      </td>
    </tr>

    <tr>
      <td>
        Delete Fax Line
      </td>

      <td>
        DELETE /v1/Accounts/[Account GUID]/FaxLines/[PHONE NUMBER]
      </td>

      <td>
        DELETE 

        [/v3/fax_line/delete](/api/fax-line/delete)
      </td>
    </tr>
  </tbody>
</table>

## Additional Functionality

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

<table>
  <thead>
    <th>
      Endpoint
    </th>

    <th>
      v3
    </th>
  </thead>

  <tbody>
    <tr>
      <td>
        Download Fax Files
      </td>

      <td>
        POST 

        [/v3/fax/files/\[FAX ID\]](/api/fax/files)
      </td>
    </tr>

    <tr>
      <td>
        Delete Fax
      </td>

      <td>
        DELETE 

        [/v3/fax/\[FAX ID\]](/api/fax/delete)
      </td>
    </tr>

    <tr>
      <td>
        Get Fax Line
      </td>

      <td>
        GET 

        [/v3/fax_line/](/api/fax-line/get)
      </td>
    </tr>

    <tr>
      <td>
        Add User to Fax Line
      </td>

      <td>
        PUT 

        [/v3/fax_line/add_user](/api/fax-line/add-user)
      </td>
    </tr>

    <tr>
      <td>
        Remove Fax Line Access
      </td>

      <td>
        PUT 

        [/v3/fax_line/remove_user](/api/fax-line/remove-user)
      </td>
    </tr>
  </tbody>
</table>

## 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](https://faq.hellosign.com/hc/en-us/articles/218532468-Can-you-give-me-an-example-of-a-callback-event).

The updated structure will be POSTed to the v3 callback url settings that can be specified on the [API Settings](https://app.hellofax.com/home/myAccount?current_tab=api) page.
These new settings have the same expectations as the Sign API and require the same response detailed in the [Events and Callbacks Walkthrough](/docs/guides/events-and-callbacks/walkthrough#responding-to-events).

![Fax API Callback URL Setting](https://files.buildwithfern.com/https://dropbox123432.docs.buildwithfern.com/304eb6a619e250bda96eb78697bc63502ba5307893ddd933b6e52bdcfbac1f7f/docs/fax/api-setting-callbacks.png)

### Example v3 Payload

```json
    {
      "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](https://app.hellofax.com/home/myAccount?current_tab=api) page.

![Fax API Delete Setting](https://files.buildwithfern.com/https://dropbox123432.docs.buildwithfern.com/32a7eca9d065ae2a51d8d15e2a9f1edbad4b894f7a96613a95b1e5cf087f5ed5/docs/fax/api-setting-delete-fax.png)

## 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.