# 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://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 server that will route your call to the appropriate geography region automatically: ```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. 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 ### WebhookBasicAuth You can validate whether a webhook is genuine by providing credentials you set and will check on your server side along with the callback URL, as in this example: `https://username:password@www.YourWebhookWebsite.com` Type: http Scheme: basic ### 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/_bundle/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, unless 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 https://), 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. created>=2021-01-01&startTime<=2021-01-10 ### 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. ### Download fax content - [GET /faxes/{id}/file](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/getfaxfilebyid.md): Download the fax content. ### 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 (deprecated) - [GET /faxes/{id}/file.{fileFormat}](https://developers.sinch.com/docs/fax/api-reference/fax/faxes/getfaxfilebyiddeprecated.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 'file' application/pdf attachment. 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 'file' application/pdf attachment. 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. **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. ## 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 delay before each retry, which increases as follows: | Retry number | Delay | Cumulative wait | | ------------ | ---------- | ------------ | | 1 | 5 minutes | 5 minutes | | 2 | 10 minutes | 15 minutes | | 3 | 20 minutes | 35 minutes | | 4 | 30 minutes | 1 hour 5 minutes | | 5-16 | 6 hours | up to ~3 days | ### IP Addresses Notifications are sent from the following IP addresses so you can add them to allowlists if necessary. | IP address | Description | | ---------- | ----------- | | 34.232.249.173 | use1 (East) | | 44.226.9.173 | usw2 (West) | ### 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 'file' application/pdf attachment. 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 'file' application/pdf attachment. 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 both. ### 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 ## Domains 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. ### List domains - [GET /services/{serviceId}/domains](https://developers.sinch.com/docs/fax/api-reference/fax/domains/listdomains.md): List existing domains for the specified service. ### Create a domain - [POST /services/{serviceId}/domains/{domainName}](https://developers.sinch.com/docs/fax/api-reference/fax/domains/createdomain.md): Creates a new domain on the specified service to host email templates. ### Get domain - [GET /services/{serviceId}/domains/{domainName}](https://developers.sinch.com/docs/fax/api-reference/fax/domains/getdomain.md): Retrieve a specific domain for the specified service. ### Delete domain - [DELETE /services/{serviceId}/domains/{domainName}](https://developers.sinch.com/docs/fax/api-reference/fax/domains/deletedomain.md): Delete a specific domain for the specified service. ### Verify domain - [GET /services/{serviceId}/domains/{domainName}:verify](https://developers.sinch.com/docs/fax/api-reference/fax/domains/verifydomain.md): Verify a specific domain for the specified service. ## Templates 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. ### List templates for domain - [GET /services/{serviceId}/domains/{domainName}/templates](https://developers.sinch.com/docs/fax/api-reference/fax/templates/listtemplates.md): List templates for a specific domain for the specified service. ### Get template - [GET /services/{serviceId}/domains/{domainName}/templates/{templateName}](https://developers.sinch.com/docs/fax/api-reference/fax/templates/gettemplate.md): Retrieve a named template for a specific domain for the specified service. ### Update template - [PUT /services/{serviceId}/domains/{domainName}/templates/{templateName}](https://developers.sinch.com/docs/fax/api-reference/fax/templates/updatetemplate.md): Update a template for a specific domain for the specified service. ## 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.