Sinch Fax API

openapi: 3.2.0
info:
  version: '3.0'
  title: Fax API
  description: 'This document provides a detailed user guide and reference documentation on the Fax REST API.


    If you have questions please contact us via our [support portal](https://support.sinch.com) and a team member will be happy to assist.


    {% admonition type="info" name="Note:" %}

    You must create an account on our support portal if you do not have one.

    {% /admonition %}


    ## Authentication


    For information on how to authenticate API requests we support two methods [Basic](https://developers.sinch.com/docs/fax/api-reference/authentication/basic) or [Oauth2](https://developers.sinch.com/docs/fax/api-reference/authentication/oauth)


    ## Global URL


    Sinch has a global Fax API server:


    ```shell

    https://fax.api.sinch.com/

    ```


    ## Formats


    By default, all API calls return a JSON response unless otherwise specified.


    ### Date time fields


    All date and time fields are in UTC format unless otherwise specified.


    ## Deletion and data retention


    If you have enabled storage, we retain fax logs and media for 13 months which you can access via the API. After 13 months, media and logs are deleted.


    ## Errors & statuses


    Find error codes and explanations [here](https://developers.sinch.com/docs/fax/api-reference/fax/error-messages).


    ## Webhooks


    You can configure your service to use webhooks to send a request to you when faxes arrive or complete on your account.


    **Note:** When webhooks with Basic authentication credentials are shown in GET requests, the credentials are masked with `***`` symbols. It is not possible to retrieve previously-set credentials through the API.

    '
  contact:
    name: Contact Fax API Team
    url: https://www.sinch.com/contact/
    email: faxteam@sinch.com
  license:
    url: https://www.sinch.com/legal
    name: MIT
servers:
- url: https://fax.api.sinch.com
  description: v3.0 of the Fax API
security:
- BasicAuth: []
- OAuth2: []
tags:
- name: Faxes
  description: 'The Fax API allows you to send and receive faxes. You can send faxes to a single recipient or to multiple recipients. You can also receive faxes and download them.


    To send a TEST Outbound fax you can send a fax TO +19898989898.  This will emulate all aspects of a real fax without charging your account.'
- name: Notifications
  description: "Webhooks allow you to get updates in real-time about the status of your faxes. Webhooks are triggered by events such as the completion of a fax, and transmit information about the state of that fax to you via HTTP(S) or email.\nHTTP webhooks are multipart/form-data POST requests, and should be processed like form submissions.\n\n**Note:** When webhooks with Basic authentication credentials are shown in GET requests, the credentials are masked with `***`` symbols. It is not possible to retrieve previously-set credentials through the API.\n\n## Setting up webhooks\n\nDepending on the type of webhook, you can configure the callback URLs in a few ways:\n\n  **Incoming fax notification**:\n\n  - On your [Fax service](https://dashboard.sinch.com/fax/services) in the dashboard.\n  - Using the [API when configuring your service](https://developers.sinch.com/docs/fax/api-reference/fax/services/createnotificationwebhook). This is required to receive notifications about incoming calls to your Sinch number.\n\n  **Fax completed notification**:\n\n  - By including the `callbackUrl` property in the request body when you send a fax via the `/faxes` endpoint.\n\n### Retries\n\nIf a webhook fails, we will automatically retry sending the fax up to 16 times. There will be a delay before each retry, which increases as follows:\n\n| Retry number | Delay   | Cumulative wait |\n| ------------ | ---------- | ------------ |\n| 1            | 5 minutes  | 5 minutes |\n| 2            | 10 minutes | 15 minutes |\n| 3            | 20 minutes | 35 minutes |\n| 4            | 30 minutes | 1 hour 5 minutes |\n| 5-16         | 6 hours    | up to ~3 days |\n\n### IP Addresses\n\nNotifications are sent from the following IP addresses so you can add them to allowlists if necessary.\n\n| IP address | Description |\n| ---------- | ----------- |\n| 34.232.249.173 | use1 (East) |\n| 44.226.9.173 | usw2 (West) |"
- name: Fax to Email
  description: "The Emails endpoint allows you to configure the Fax to Email functionality. Fax to Email allows you to send an email and then receive a fax on your Sinch number or send a fax and have it sent to your email address.\nThe service supports sending incoming faxes to multiple email addresses and having many numbers associated with one email address.\n\n## Setting up fax to email\n\nYou can configure fax to email in two different places:\n\n  - In the dashboard on a number-by-number basis or by adding an email address and associating many numbers to one email address.\n  - Via the API when you create a number or update a number, or by using the email endpoint to set it up directly\n  - Supported fax to email file types are Word, PDF, and TIF\n\n## Fax to email example\n\nThe following example shows how to configure Fax to Email using the API:\n  1. Buy a number in the dashboard and assign it to a Fax service\n  2. Add your email and associate it with the number you bought in step 1.\n\n```json\nPOST https://fax.api.sinch.com/v3/projects/{projectId}/services/{serviceId}/emails\n {\n    \"email\": \"user@domain.com\",\n    \"phoneNumbers\": [\n       {\n        \"number\": \"+14155552222\",\n        \"permissions\": \"both\"\n       }\n    ]\n}\n```\n\nNow you can use your email client with the above email address to fax.\n\n## Send a fax using email\n\nMake sure the email address you are sending from is added to your account. You can add it in the dashboard under the **Fax to email** of your Fax service in the [Build dashboard]https://dashboard.sinch.com/fax/fax-to-email) or via the API.\n\nSend an email to {PhoneNumberToSendFaxTo}@sinchfax.com with the following:\n\n| Field | Description |\n| ----- | ----------- |\n| **Subject:** | If you have multiple phone numbers associated with the email address, enter the number you want to use. If left blank, the first number that we find will be used. |\n| **Body:** | By default, the email body is not used.  |\n| **Attachments** | Add any attachments you want to fax. If you want to specify the order of pages we recommend that you create one document with all pages in the correct order and attach that document. If you attach multiple documents we will merge them  into one document in the order we receive them. |\n\n\n## Receive a fax using email\n\nWhen you receive a fax, we will send you an email with the following:\n| Field | Description |\n| ----- | ----------- |\n| **From:** | The number the fax was sent from, e.g. +15612600684@sinchfax.com |\n| **Subject:** | You have received a new fax on {+1 234 555 5555} |\n| **Body:** | The page count and other metadata are HTML only, and will not appear in plain text in the email. |\n\nThere will be one PDF attachment with the fax content.\n\n## Configuring your email system for best performance\n\nMake sure you allowlist `sinchfax.com` and `sinch.com` in your spam filter to ensure delivery to your inbox, both on client and server side.\nEnsure your mail server is setup correctly and not on spam lists.\n\n## Encryption\n\nAll emails are sent using TLS during transport from Sinch."
- name: Domains
  description: You can create email domains to handle the email notifications for your fax service. The operations in this endpoint allow you to create, manage, and verify your email domains.
- name: Templates
  description: You can use templates to control the look and content of the email notifications for your fax service. These templates are stored on a email domain that you can configure and manage using the `/domains` endpoints.
- name: Cover pages
  description: "You can add cover pages to Sinch Fax either via the API or the [Build dashboard](https://dashboard.sinch.com).\n\nA Fax service can have 0 or more cover pages configured.\n\n### When cover pages are added\n\n#### Via dashboard\n\nIn the **Send Fax** tab you can select the option to ***select a cover page from a drop down***. When one is selected it will use that cover page on all outbound faxes.\n\n**Note:** If you are using Fax to Email, this is currently the only way to add a cover page to your faxes.\n\n#### Via API\n\nWhen sending a fax using the API, you can specify `coverPageId` and supply your own cover page data.\n\n### How to create a cover page\n\nCreate a PDF that fits your brand. It should have all the standard static content you need to stay compliant. Insert tags that will be replaced at run time by us for dynamic content.\n\n#### Automatic fields\n\nIf we find the tags described in the table below, we will replace these tokens with fax metadata.\n\n|Tag | Content | Example |Description |\n| ---- | ----- | ----- | ----- |\n|{{from}}| string | +15557897890 | Your Sinch number that you used to send the fax. |\n|{{to}}| string | +15551231234 |  The number to which you are sending the fax. |\n|{{date}}| date | 2/4/2025 | The date when the fax was sent. |\n|{{pageCount}}| number | 52 | The total number of pages to be transmitted. |\n\n### Specifying your own dynamic fields in API calls\n\nWhen sending faxes via API you can add any tags you like with `{{}}`` syntax and set those in your app calls for cover page data.\n\nExample:\n  If you would like to add the recipient's name and your own message on the cover page:\n\n```json\n/// in your template pdf\nFax to : {{to_name}}\n{{my_custom_message}}\n\n{\n  ///other fax fields removed for clarity\n  coverPageData: {\n    \"to_name\": \"Dr. John Smith\",\n    \"my_custom_message\": \"I know you are busy please take on this patient\"\n    }\n}\n```"
- name: Error Messages
  description: "## Fax Error Messages\n\nWhen your receive a callback from the fax api notifying you of a failure, it will contain two values\nthat can help you understand what went wrong: an errorCode and an type.\n\nThe type will give you a general idea of why the operation failed, whereas the errorCode describes the issue in more detail. Below we list the error_codes for the API, segmented by their corresponding error_type.\n\n{% partial file=\"/partials/fax/errors/_schemas.md\"/ %}\n\n## General Error Messages\n\nRequest errors are returned as HTTP status codes. The following table lists the possible error codes and their meaning.\n\nThe type will give you a general idea of why the operation failed, whereas the errorCode describes the issue in more detail. Below we list the error_codes for the API, segmented by their corresponding error_type.\n\n## Http Error Codes\n\n### 400 - Bad Request\n\n```json\n{\n  \"code\": \"404\",\n  \"error\": \"Bad Request\",\n  \"message\": \"\n    The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.\n    It could be invalid JSON, missing required fields, or other issues.\"\n}\n```\n\n### 401 - Unauthorized\n\nEmpty body, or you have the wrong API key, secret, or project.\n\n### 402 - Payment required\n\n```json\n{\n  \"code\": \"402\",\n  \"error\": \"Payment required\",\n  \"message\": \"You have reached 0 balance on your account please make a payment.\"\n}\n```\n\n\n### 404 - Not found\n\n```json\n{\n  \"code\": \"404\",\n  \"error\": \"Not found\",\n  \"message\": \"The resource is not found, not available, or does not exist.\"\n}\n```\n\n### 422 - Unprocessable Content (Invalid parameters)\n\n```json\n{\n  \"code\": \"422\",\n  \"error\": \"Invalid parameters\",\n  \"message\": \"The request could not be understood by the server due to malformed syntax.\n     The client SHOULD NOT repeat the request without modifications.\"\n  details: {\n    fieldViolations: [\n      {\n        field: \"to\",\n        description: \"The (+15551) is not a valid phone number\"\n      }\n    ]\n\n  }\n```\n\n### 429 Rate limit exceeded\n\nRate limit exceeded, please back off and try again later. If you need higher rate please contact support.\n\n\n### 500 - Internal Server Error\n\nProbably no body, but if there is a body it will look like this:\n\n```json\n{\n  \"code\": \"500\",\n  \"error\": \"Internal service error\",\n  \"message\": \"Most likely a temporary issue, please try again later. If the problem persists, please back of on this request and contact support.\"\n}\n```\n\n### 800 - URL Connection Error\n\nThis non-http code will be used when there is an issue connecting to the designated callback URL. The response will look like this:\n\n```json\n{\n  \"error\": \"Could not connect to URL: https://123.456.789.00\"\n}\n```\n\n\n## Error object\n\nPlease note that the response code is probably the most important part of the response, but the error object will contain more information about the error.\nNot all errors return this object, and the `details` object is not always present.\n\n{% json-example \n  value={\n    \"$ref\": \"./fax.yaml#/components/schemas/Error\"\n  }\n/%}"


# --- truncated at 32 KB (148 KB total) ---
# Full source: https://artifacts.apis.io/sinch/openapi/sinch-fax-api-openapi.yml