Add a cover page to your service
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/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}
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
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
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
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
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.
When sending a fax using the API, you can specify coverPageId and supply your own cover page data.
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.
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. |
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:
/// 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"
}
}- v3.0 of the Fax APIhttps://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/coverPages
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/coverPages' \
-H 'Content-Type: application/json' \
-d '{
"name": "Acme Company cover page",
"file": {
"fileContent": "string",
"fileType": "PDF"
}
}'The added coverpage, or an Error
A PDF Cover encoded as base64
The Id of the project associated with the call.
Example: "ae00f005-e392-44dc-b3f5-a657a2684dg3"
Response
application/json
{ "id": "string", "name": "Acme Company cover page", "file": { "fileContent": "string", "fileType": "PDF" }, "projectId": "ae00f005-e392-44dc-b3f5-a657a2684dg3", "serviceId": "01GVRB50KEQFFE1SGMPFRNBG6J", "createdTime": "2019-08-24T14:15:22Z", "updatedTime": "2019-08-24T14:15:22Z" }
- v3.0 of the Fax APIhttps://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/coverPages
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/coverPages'List of coverpages Error
Response
application/json
{ "coverPages": [ { … } ], "page": 0, "totalPages": 0, "pageSize": 0, "totalItems": 0 }
- v3.0 of the Fax APIhttps://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/coverPages/{coverPageId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
-u <username>:<password> \
'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/coverPages/{coverPageId}'- v3.0 of the Fax APIhttps://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/coverPages/{coverPageId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/coverPages/{coverPageId}'The requested cover page, or an Error
A PDF Cover encoded as base64
The Id of the project associated with the call.
Example: "ae00f005-e392-44dc-b3f5-a657a2684dg3"
Response
application/json
{ "id": "string", "name": "Acme Company cover page", "file": { "fileContent": "string", "fileType": "PDF" }, "projectId": "ae00f005-e392-44dc-b3f5-a657a2684dg3", "serviceId": "01GVRB50KEQFFE1SGMPFRNBG6J", "createdTime": "2019-08-24T14:15:22Z", "updatedTime": "2019-08-24T14:15:22Z" }
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