Migrating from Phaxio v2.1 to Sinch Fax API

This guide will give you a background and overview of the major changes between Phaxio and Sinch Fax API. The primary driver for us to move Fax functionality to the Sinch Dashboard is we want to make it easier for you to buy, consume, and monitor all your communication workflows in one place.

Overview of migration activities

Below is an overview of the migration process with estimated timelines based on how long it took other customers to migrate along side our internal testing. It's important to note especially when it comes to moving numbers this is not necessarily days worth of work, but instead it's a lot of lead time waiting for various steps in the process, and we have chosen leadtime to rollout changes in a controlled manner.

Read more at the bottom of this document

New Dashboard

The dashboard is all new and you will find it here. You must create a new Sinch account, as it is not simply an upgrade from Phaxio. Below are some new features that we think you may find useful:

• Multiple users on your account
• Different webhooks per use case using services
• Better reporting on errors and API calls
• Ability to use your enterprise SSO
• Project model to separate your use cases / environments
• Access to a wide range of products from Sinch
• Advanced billing capabilities

We hope you like the new dashboard and are looking forward to hear what you think.

Account Structure Differences

Phaxio v2.1

• Single account structure with API keys
• Direct API key authentication
• No concept of projects
• Numbers managed at account level

Sinch Fax API

• Project-based structure enables billing and security per project/workspace
• API authentication through project-specific tokens
• Resources organized by projects
• Numbers managed at project level Read more about projects in our FAQ https://community.sinch.com/t5/Build-Dashboard/What-is-a-project-and-how-to-manage-projects/ta-p/12693

Authentication

Because it's a new account, new API keys are required and we now offer you more ways to authenticate.

Phaxio Authentication

Phaxio uses basic authentication and you can have one or many API keys on your account.

Sinch Authentication and API Structure

Sinch Fax API v3 supports basic authentication and OAuth 2.0 if you prefer. All keys are tied to a project.

All Sinch Fax API v3 endpoints follow this structure: https://fax.api.sinch.com/v3/projects/{projectId}/[resource]

Where:

• {projectId} is your Sinch project ID
• [resource] is the API resource (e.g., 'faxes', 'numbers', etc.)

Read more about projects

Read more about Authentication.

API changes

Phaxio v2.1 is not backwards compatible at all with Sinch Fax API. While you will find many similarities between v2.1 and other Sinch APIs, we had to create breaking changes because we took the opportunity to try to be consistent with other Sinch APIs such as path structure and new authentication mechanisms with projects. One thing you will notice is all fields are now camelCase instead of snake_case among other things. Another difference compared to Phaxio is that we employ Sinch guidelines and try to return as much of a resource that is created, so for example when you send a fax, you will get a fax resource back with as much information that is available.

Removed features/Different workflows

Below are a few features we no longer support in V3

• One recipient per fax: You can still send to multiple recipients, but we will on the backend create multiple faxes and you can follow up on each of them. 99.95% of the faxes we send are to one recipient. For you to be able to track delivery better in webhooks, we recommend that you change your code and workflow to create many faxes and track each faxid if you send bulk.
• Inflight webhooks: We no longer notify per page on incoming faxes, due to lack of usage
• Phone call data: In webhooks we no longer supply phone call metadata, this is a feature that may come back if demand is there
• Barcode generation: The possibility to create barcodes, but we still support reading of bar codes
• Separation of send/receive webhooks and Setting global send webhook: If you want to be notified on completion of a fax, you have to send the callback URL in your API call
• Mailto: in webhook: If you were using webhook config to mail faxes to your self, you now instead configure fax to email for this
• Webhook signatures: Removed due to low usage, at the moment V3 does not support webhook signatures, if you are interesting in this feature or any other security method for us calling your server reach out to me christian@sinch.com
• No ATA support: Removed due to low usage, If you are interested in this feature reach out to let me know

New features

• Fax to email: Ability to fax in both directions using email
• Mutliple webhooks on account: Using services and API calls you can now use Sinch Fax API without leaving your mail client.
• Better document conversion: Higher quality and more secure document conversion engine
• Send filecontent as json: If you prefer you can send files as a JSON payload
• Webhooks in json format: If you prefer base64 encoded files, also receive faxes with JSON payload.

Sending Faxes

Phaxio V2

# Phaxio - form data
curl -X POST "https://api.phaxio.com/v2.1/faxes" \
     -u "your_api_key:your_api_secret" \
     -F "to=+1234567890" \
     -F "content_url="https://yourserver/file.pdf" \
     -F "file=@/path/to/document.pdf" \
     -F "caller_id=+1987654321"

Sinch V3

Sinch v3 supports three methods for sending files:

1. Form Data (most common, similar to Phaxio)
   Copy

   Copied

   # Sinch - form data
   curl -X POST "https://fax.api.sinch.com/v3/projects/{projectId}/faxes" \
      -u "your_api_key:your_api_secret" \
      -F "to=+1234567890" \
      -F "file=@/path/to/document.pdf" \
      -F "from=+1987654321"

2. Content URL
   Copy

   Copied

   # Sinch - content URL
   curl -X POST "https://fax.api.sinch.com/v3/projects/{projectId}/faxes" \
      -u "your_api_key:your_api_secret" \
      -H "Content-Type: application/json" \
      -d '{
          "to": "+1234567890",
          "contentUrl": "https://your-file-url.com/document.pdf",
          "from": "+1987654321"
      }'

3. Base64 Encoded Content
   Copy

   Copied

   # Sinch - base64
   curl -X POST "https://fax.api.sinch.com/v3/projects/{projectId}/faxes" \
      -u "your_api_key:your_api_secret" \
      -H "Content-Type: application/json" \
      -d '{
          "to": "+1234567890",
          "files": [{
              "data": "base64_encoded_content"
          }],
          "from": "+1987654321"
      }'

Migration Note:

• The form data method in Sinch v3 provides a familiar experience for those migrating from Phaxio.
• In order to get a notification of an outbound fax completion you need to set callbackUrl in your request. This enables flexible custom callbacks for each fax.
• You can keep your existing file handling logic when using form data, only minor field name changes.
• The contentUrl and base64 options provide additional flexibility when needed.

Key Differences:

• Project ids
• Camel casing
• Different parameter names (caller_id vs from)

Checking Fax Status

While this is supported, we strongly recommend using webhooks for any updates on faxes.

Phaxio

# Phaxio status check
curl -X GET "https://api.phaxio.com/v2.1/faxes/{faxId}" \
     -u "api_key:api_secret"

Sinch

# Sinch status check
curl -X GET "https://fax.api.sinch.com/v3/projects/{projectId}/faxes/{faxId}" \
     -u "your_api_key:your_api_secret" \

Key Differences:

• Project ids
• Camel casing/Fax object
• Different parameter names (caller_id vs from)

Receiving Faxes

One of the major things we don't support in V3 is signed requests. Instead, we support basic authentication.

Phaxio

# Phaxio webhook example payload
# multipart formdata
{
  "event_type": "fax_completed",
  "file": "as stream",
  "fax": {
    "from_number": "+14155552222",
    "caller_id": null,
    "status": "success",
    "recipients": [],
    "completed_at": "2025-01-14T23:30:01.000Z",
    "is_test": false,
    "cost": 0,
    "num_pages": 0,
    "id": 123,
    "tags": false,
    "barcodes": false,
    "direction": "received",

    "to_number": "+14155552233",
    "created_at": "2025-01-14T23:30:01.000Z",
    "error_id": 132
  }
}

Sinch

# Sinch webhook example payload
# multipart formdata OR json
{
  "event": "INCOMING_FAX",
  "eventTime": "2021-11-01T23:25:67Z",
  "fax": {
    "id": "01HDFHACK1YN7CCDYRA6ZRMA8Z",
    "direction": "INBOUND",
    "from": "+14155552222",
    "to": "+14155553333",
    "numberOfPages": 1,
    "status": "COMPLETED",
    "price": {
      "amount": "0.00",
      "currencyCode": "USD"
    },
    "createTime": "2021-11-01T23:25:67Z",
    "completedTime": "2021-11-01T23:25:67Z",
    "projectId": "YOUR_PROJECT_ID",
    "serviceId": "YOUR_SERVICE_ID"
  },
  "file": "{application/pdf}"
}

Feature Comparison and Migration Considerations

Numbers Management

• Phaxio : Numbers managed at account level
• Sinch : Numbers managed per project

Migration step: Create projects and reassign and port numbers See Numbers API for further information about buying and configuring numbers

File Handling

• Phaxio : URL and Direct file uploads
• Sinch : As above plus base64 encoded content

  Migration step: Nothing if desired

Webhook Security

• Phaxio : Built-in signature validation, basic auth
• Sinch : Basic auth

Migration step:Remove sigature validation

Fax statuses

Error Status Codes

• Phaxio : Custom status codes
• Sinch : Standard HTTP status codes, with rich error object
  Copy

  Copied

  ///not found
  {
  "code": "404",
  "error": "Bad Request",
  "message": "
      The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
      It could be invalid JSON, missing required fields, or other issues."
  },
  ///invalid request
  {
  "code": "422",
  "error": "Invalid parameters",
  "message": "The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.",
  "details": {
      "fieldViolations": [
      {
          "field": "to",
          "description": "The (+15551) is not a valid phone number"
      }
      ]
  }
  }

Migration Steps

1. Account Setup
   • Create Sinch account
   • Create project(s)
   • Generate API tokens
   • Map existing numbers to projects
2. Code Updates
   • Update authentication mechanism
   • Modify API endpoint calls
   • Update parameter names and structures
   • Update webhook handlers
   • If necessary implement workflow to move customers one at a time
3. Testing
   • Test sending faxes
   • Verify webhook functionality
   • Validate number routing
   • Check status reporting
4. Production Migration
   • Plan porting with Sinch support
   • Deploy updated code
   • Update DNS/webhook endpoints
   • Monitor for issues
   • Keep Phaxio active during transition