# Fax API 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://tickets.sinch.com/plugins/servlet/desk/portal/31/create/1559) 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.md) or [Oauth2](https://developers.sinch.com/docs/fax/api-reference/authentication/oauth.md) ## Global URL Sinch has a global server that will route your call to the appropriate geography region automatically: ```shell https://fax.api.sinch.com/ ``` or, you can also specify what location you want to call by prefixing the above global URL with one of the region codes in the table below: | Region | URL | | ----------------- | ----------------------- | | US East Coast | use1.fax.api.sinch.com | | Europe | eu1.fax.api.sinch.com | | South America | sae1.fax.api.sinch.com | | South East Asia 1 | apse1.fax.api.sinch.com | | South East Asia 2 | apse2.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 In general we retain fax logs and media for 13 months and you can access that via the API. ## 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. Version: 3.0 License: MIT ## Servers v3.0 of the Fax API ``` https://fax.api.sinch.com/v3/projects/{projectId} ``` Variables: - `projectId`: The project with which you are working. Default: "YOUR_project_id" ## Security ### BasicAuth The user name and password is your keyId and key secret from the [Access keys sections](https://dashboard.sinch.com/settings/access-keys) Type: http Scheme: basic ### OAuth2 The user name and password is your key id and key secret from the [Access keys sections](https://dashboard.sinch.com/settings/access-keys) Type: oauth2 ## Download OpenAPI description [Fax API](https://developers.sinch.com/_spec/docs/fax/api-reference/fax.yaml) ## Faxes 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. ### Send a fax - [POST /faxes](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/sendfax.md): Create and send a fax. Fax content may be supplied via one or more files or URLs of supported filetypes. This endpoint supports the following content types for the fax payload: - Multipart/form-data - Application/json We will however always return a fax object in the response in application json. If you supply a callbackUrl the callback will be sent as multipart/form-data with the content of the fax as an attachment to the body, you specify callbackUrlContentType as application/json. #### file(s) Files may be included in the POST request as multipart/form-data parts. #### contentUrl Any URL on the Internet (including ones with basic authentication), and we'll pull it down and make it a fax. This might be useful to you if you're using a web framework for templates and creating fax files. Please note: If you are passing fax a secure URL (starting with ), make sure that your SSL certificate (including your intermediate cert, if you have one) is installed properly, valid, and up-to-date. ### List faxes - [GET /faxes](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/getfaxes.md): List faxes sent (OUTBOUND) or received (INBOUND), set parameters to filter the list. Example: Return calls made between 1st of January 2021 and 10th of January 2021. ### Get fax - [GET /faxes/{id}](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/getfaxinfoperid.md): Get fax information using the ID number of the fax. ### Delete fax content - [DELETE /faxes/{id}/file](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/deletefaxcontentbyid.md): Delete the fax content for a fax using the ID number of the fax. Please note that this only deletes the content of the fax from storage. ### Download fax content - [GET /faxes/{id}/file.{fileFormat}](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/getfaxfilebyid.md): Download the fax content. ### Incoming fax event - [POST incomingFax](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/incomingfaxevent.md): This webhook is triggered when a fax is received on a Sinch number associated with a service. The webhook will contain information about the fax, such as the sender, the recipient, and the content of the fax. You set the callback URL for incoming fax events on the service, either through the dashboard or using the service API. ### Example payloads Multipart/form-data request payloads are encoded as forms with a content type of JSON and the actual fax content as a . Application/json request payloads are a JSON object with the file encoded as a base64 string as part of the JSON object. ### Fax completed - [POST faxCompleted](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/faxcompletedcallback.md): Triggered when the fax has been completed. The callback will contain information about the fax, such as the sender, the recipient, and the content of the fax. You must set the callback URL where you want the callback sent when you make a send fax request. ### Incoming fax event - [POST incomingFax](https://developers.sinch.com/docs/fax/api-reference/fax/notifications/incomingfaxevent.md): This webhook is triggered when a fax is received on a Sinch number associated with a service. The webhook will contain information about the fax, such as the sender, the recipient, and the content of the fax. You set the callback URL for incoming fax events on the service, either through the dashboard or using the service API. ### Example payloads Multipart/form-data request payloads are encoded as forms with a content type of JSON and the actual fax content as a . Application/json request payloads are a JSON object with the file encoded as a base64 string as part of the JSON object. ### Fax completed - [POST faxCompleted](https://developers.sinch.com/docs/fax/api-reference/fax/notifications/faxcompletedcallback.md): Triggered when the fax has been completed. The callback will contain information about the fax, such as the sender, the recipient, and the content of the fax. You must set the callback URL where you want the callback sent when you make a send fax request. ## Notifications 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. HTTP webhooks are multipart/form-data POST requests, and should be processed like form submissions. ## Setting up webhooks Depending on the type of webhook, you can configure the callback URLs in a few ways: **Incoming fax notification**: - On your [Fax service](https://dashboard.sinch.com/fax/services) in the dashboard. - 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. **Fax completed notification**: - By including the `callbackUrl` property in the request body when you send a fax via the `/faxes` endpoint. ### Retries If a webhook fails, we will automatically retry sending the fax up to 16 times. There will be a back off before each retry, which increases as follows: | Retry number | Back off | | ------------ | ---------- | | 1 | 5 minutes | | 2 | 10 minutes | | 3 | 20 minutes | | 4 | 30 minutes | | 5-16 | 6 hours | ### Incoming fax event - [POST incomingFax](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/incomingfaxevent.md): This webhook is triggered when a fax is received on a Sinch number associated with a service. The webhook will contain information about the fax, such as the sender, the recipient, and the content of the fax. You set the callback URL for incoming fax events on the service, either through the dashboard or using the service API. ### Example payloads Multipart/form-data request payloads are encoded as forms with a content type of JSON and the actual fax content as a . Application/json request payloads are a JSON object with the file encoded as a base64 string as part of the JSON object. ### Fax completed - [POST faxCompleted](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/faxcompletedcallback.md): Triggered when the fax has been completed. The callback will contain information about the fax, such as the sender, the recipient, and the content of the fax. You must set the callback URL where you want the callback sent when you make a send fax request. ### Incoming fax event - [POST incomingFax](https://developers.sinch.com/docs/fax/api-reference/fax/notifications/incomingfaxevent.md): This webhook is triggered when a fax is received on a Sinch number associated with a service. The webhook will contain information about the fax, such as the sender, the recipient, and the content of the fax. You set the callback URL for incoming fax events on the service, either through the dashboard or using the service API. ### Example payloads Multipart/form-data request payloads are encoded as forms with a content type of JSON and the actual fax content as a . Application/json request payloads are a JSON object with the file encoded as a base64 string as part of the JSON object. ### Fax completed - [POST faxCompleted](https://developers.sinch.com/docs/fax/api-reference/fax/notifications/faxcompletedcallback.md): Triggered when the fax has been completed. The callback will contain information about the fax, such as the sender, the recipient, and the content of the fax. You must set the callback URL where you want the callback sent when you make a send fax request. ## Fax to Email 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. The service supports sending incoming faxes to multiple email addresses and having many numbers associated with one email address. ## Setting up fax to email You can configure fax to email in two different places: - In the dashboard on a number-by-number basis or by adding an email address and associating many numbers to one email address. - Via the API when you create a number or update a number, or by using the email endpoint to set it up directly - Supported fax to email file types are Word, PDF, and TIF ## Fax to email example The following example shows how to configure Fax to Email using the API: 1. Buy a number in the dashboard and assign it to a Fax service 2. Add your email and associate it with the number you bought in step 1. ```json POST https://fax.api.sinch.com/v3/projects/{projectId}/services/{serviceId}/emails { "email": "user@domain.com", "phoneNumbers": [ "+14155552222" ] } ``` Now you can use your email client with the above email address to fax. ## Send a fax using email Make sure the email address you are sending from is added to your account. You can add it in the dashboard under [Fax to email](https://dashboard.sinch.com/fax/fax-to-email) or via the API. Send an email to {PhoneNumberToSendFaxTo}@sinchfax.com with the following: | Field | Description | | ----- | ----------- | | **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. | | **Body:** | By default, the email body is not used. | | **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. | ## Receive a fax using email When you receive a fax, we will send you an email with the following: | Field | Description | | ----- | ----------- | | **From:** | The number the fax was sent from, e.g. +15612600684@sinchfax.com | | **Subject:** | Fax received on {your sinch number the fax was sent to} | | **Body:** | The body will contain data such as number of pages or other relevant metadata of the fax. | There will be one PDF attachment with the fax content. ## Configuring your email system for best performance Make sure you allowlist `sinchfax.com` and `sinch.com` in your spam filter to ensure delivery to your inbox, both on client and server side. Ensure your mail server is setup correctly and not on spam lists. ## Encryption All emails are sent using TLS during transport from Sinch. ### List emails for a number - [GET /services/{id}/numbers/{phoneNumber}/emails](https://developers.sinch.com/docs/fax/api-reference/fax/fax-to-email/getemailsfornumber.md): List any emails for a number. ### List emails - [GET /services/{serviceId}/emails](https://developers.sinch.com/docs/fax/api-reference/fax/fax-to-email/getemailsforproject.md): List emails for the project. ### Add an email - [POST /services/{serviceId}/emails](https://developers.sinch.com/docs/fax/api-reference/fax/fax-to-email/createemailforproject.md): Add an email to the specified service to be used for sending and receiving faxes. Default settings for permissions parameter is . ### Update numbers for email - [PUT /services/{serviceId}/emails/{email}](https://developers.sinch.com/docs/fax/api-reference/fax/fax-to-email/updateemail.md): Set the numbers for an email. ### Remove email - [DELETE /services/{serviceId}/emails/{email}](https://developers.sinch.com/docs/fax/api-reference/fax/fax-to-email/deleteemail.md): Delete an email and associated numbers to that email to disable that email from sending and receiving faxes. ### Get numbers for email - [GET /services/{serviceId}/emails/{email}/numbers](https://developers.sinch.com/docs/fax/api-reference/fax/fax-to-email/getnumbersbyemail.md): Get configured numbers for an email ## Cover pages You can add cover pages to Sinch Fax either via the API or the [Build dashboard](https://dashboard.sinch.com). A Fax service can have 0 or more cover pages configured. ### When cover pages are added #### Via dashboard In 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. **Note:** If you are using Fax to Email, this is currently the only way to add a cover page to your faxes. #### Via API When sending a fax using the API, you can specify `coverPageId` and supply your own cover page data. ### How to create a cover page Create 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. #### Automatic fields If we find the tags described in the table below, we will replace these tokens with fax metadata. |Tag | Content | Example |Description | | ---- | ----- | ----- | ----- | |{{from}}| string | +15557897890 | Your Sinch number that you used to send the fax. | |{{to}}| string | +15551231234 | The number to which you are sending the fax. | |{{date}}| date | 2/4/2025 | The date when the fax was sent. | |{{pageCount}}| number | 52 | The total number of pages to be transmitted. | ### Specifying your own dynamic fields in API calls When sending faxes via API you can add any tags you like with `{{}}`` syntax and set those in your app calls for cover page data. Example: If you would like to add the recipient's name and your own message on the cover page: ```json /// in your template pdf Fax to : {{to_name}} {{my_custom_message}} { ///other fax fields removed for clarity coverPageData: { "to_name": "Dr. John Smith", "my_custom_message": "I know you are busy please take on this patient" } } ``` ### Add cover page - [POST /services/{id}/coverPages](https://developers.sinch.com/docs/fax/api-reference/fax/cover-pages/addcoverpage.md): Add a cover page to your service ### List cover pages - [GET /services/{id}/coverPages](https://developers.sinch.com/docs/fax/api-reference/fax/cover-pages/listcoverpages.md): List all cover page to a service ### Delete a cover page - [DELETE /services/{id}/coverPages/{coverPageId}](https://developers.sinch.com/docs/fax/api-reference/fax/cover-pages/deletecoverpage.md): Remove delete a cover page from a service. ### Get a cover page - [GET /services/{id}/coverPages/{coverPageId}](https://developers.sinch.com/docs/fax/api-reference/fax/cover-pages/getcoverpage.md): Get a cover page by ID. ## Services A fax service identifies a set of configuration values. You can specify the service as a part of an API request or by associating a Sinch number with a service. This can be useful if you want to point a group of numbers to a particular incoming fax URL, or want to set the storage strategy for some of your numbers but not all of them. ## Dashboard You can manage all your fax services and their settings via the [Dashboard](https://dashboard.sinch.com/fax/services). ## Sending a test fax To send a TEST Inbound fax event in the Dashboard, enter the `IncomingWebhookUrl` on the Incoming tab and click **Save**. Then click the **SEND TEST REQUEST** button. This will emulate all aspects of a real INCOMING fax event without charging your account. ### Create a service - [POST /services](https://developers.sinch.com/docs/fax/api-reference/fax/services/createservice.md): Creates a new service that you can use to set default configuration values. ### List services - [GET /services](https://developers.sinch.com/docs/fax/api-reference/fax/services/listservices.md): Get a list of services for a project. ### Get a service - [GET /services/{id}](https://developers.sinch.com/docs/fax/api-reference/fax/services/getservice.md): Get a service resource. ### Update a Service - [PATCH /services/{id}](https://developers.sinch.com/docs/fax/api-reference/fax/services/updateservice.md): Update settings on the service. ### Remove a service - [DELETE /services/{id}](https://developers.sinch.com/docs/fax/api-reference/fax/services/removeservice.md): Removes a service from your project. ### List numbers for service - [GET /services/{id}/numbers](https://developers.sinch.com/docs/fax/api-reference/fax/services/listnumbersforservice.md): List numbers for a service.