A webhook event triggered by an fax is incoming.
Fax API (3.0)
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 and a team member will be happy to assist.
Note:
You must create an account on our support portal if you do not have one.
Sinch has a global server that will route your call to the appropriate geography region automatically:
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 |
In general we retain fax logs and media for 13 months and you can access that via the API.
Find error codes and explanations here.
Overview
Languages
Servers
v3.0 of the Fax API
https://fax.api.sinch.com/v3/projects/{projectId}/
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.
OperationsWebhooks
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.
Webhooks
Depending on the type of webhook, you can configure the callback URLs in a few ways:
Incoming fax notification:
- On your Fax service in the dashboard.
- Using the API when configuring your service. This is required to receive notifications about incoming calls to your Sinch number.
Fax completed notification:
- By including the
callbackUrlproperty in the request body when you send a fax via the/faxesendpoint.
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 |
Request
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.
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.
Security
BasicAuth
- multipart/form-data
- application/json
The value is always INCOMING_FAX for this event.
Default "INCOMING_FAX"
| Enum Value | Description |
|---|---|
| INCOMING_FAX | |
| FAX_COMPLETED | A webhook event triggered by a fax that has successfully completed. |
- v3.0 of the Fax API
https://fax.api.sinch.com/v3/projects/YOUR_project_id/incomingFax
{
"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}"
}Body
- multipart/form-data
- application/json
Always fax completed for this event.
Default "FAX_COMPLETED"
| Enum Value | Description |
|---|---|
| INCOMING_FAX | A webhook event triggered by an fax is incoming. |
| FAX_COMPLETED | A webhook event triggered by a fax that has successfully completed. |
- v3.0 of the Fax API
https://fax.api.sinch.com/v3/projects/YOUR_project_id/faxCompleted
{
"event": "FAX_COMPLETED",
"eventTime": "2021-11-01T23:25:67Z",
"fax": {
"id": "01HDFHACK1YN7CCDYRA6ZRMA8Z",
"direction": "INBOUND",
"from": "+14155552222",
"to": "+14155553333",
"numberOfPages": 1,
"status": "COMPLETED",
"price": {
"amount": "0.07",
"currencyCode": "USD"
},
"createTime": "2021-11-01T23:25:67Z",
"completedTime": "2021-11-01T23:25:67Z",
"callbackUrl": "https://www.my-website.com/callback",
"callbackUrlContentType": "multipart/form-data",
"imageConversionMethod": "HALFTONE",
"projectId": "YOUR_PROJECT_ID",
"serviceId": "YOUR_SERVICE_ID"
},
"file": "{application/pdf}"
}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.
Operations
Cover pages
You can add cover pages to Sinch Fax either via the API or the Build dashboard.
A Fax service can have 0 or more cover pages configured.
Operations
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.
Operations