Skip to content
Fax/
/Templates

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.

Authentication

For information on how to authenticate API requests we support two methods Basic or Oauth2

Global URL

Sinch has a global server that will route your call to the appropriate geography region automatically:

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.

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.

Download OpenAPI description
fax.json
fax.yaml
Overview
URL
https://www.sinch.com/contact/
Contact Fax API Team
faxteam@sinch.com
License
MIT
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.

Operations
Webhooks

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.

Webhooks

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

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.

Operations

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.

Operations

List templates for domain

Request

List templates for a specific domain for the specified service.

Security
BasicAuth or OAuth2
Path
serviceIdstringrequired

The serviceId containing the templates you want to list.

Example: 01GVRB50KEQFFE1SGMPFRNBG6J
domainNamestringrequired

The name of the domain containing the templates you want to list.

Example: yourdomain.com
curl -i -X GET \
  -u <username>:<password> \
  https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/01GVRB50KEQFFE1SGMPFRNBG6J/domains/yourdomain.com/templates

Responses

The returned templates.

Bodyapplication/jsonArray [
namestring(TemplateName)

The name of the email template.

Enum ValueDescription
successful outbound fax

The template for a successful outbound fax.

unsuccessful outbound fax

The template for an unsuccessful outbound fax.

successful inbound fax

The template for a successful inbound fax.

unsuccessful inbound fax

The template for an unsuccessful inbound fax.

createdAtstring(date-time)

The timestamp on which the template was created.

Example: "2025-10-24 19:11:50.235000+00:00"
descriptionstring

The description for the template.

Example: "Successful fax template"
]
Response
application/json
[
  {
    "name": "successful outbound fax",
    "createdAt": "2025-10-24 19:11:50.235000+00:00",
    "description": "Successful fax template"
  }
]

Get template

Request

Retrieve a named template for a specific domain for the specified service.

Security
BasicAuth or OAuth2
Path
serviceIdstringrequired

The serviceId containing the templates you want to list.

Example: 01GVRB50KEQFFE1SGMPFRNBG6J
domainNamestringrequired

The name of the domain containing the template you want to get.

Example: yourdomain.com
templateNamestring(TemplateName)required

The name of the template you want to get.

Enum ValueDescription
successful outbound fax

The template for a successful outbound fax.

unsuccessful outbound fax

The template for an unsuccessful outbound fax.

successful inbound fax

The template for a successful inbound fax.

unsuccessful inbound fax

The template for an unsuccessful inbound fax.

Example: successful outbound fax
curl -i -X GET \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/01GVRB50KEQFFE1SGMPFRNBG6J/domains/yourdomain.com/templates/successful outbound fax'

Responses

The returned template.

Bodyapplication/json
templateobject

The email template.

Response
application/json
{
  "template": {
    "name": "successful outbound fax",
    "createdAt": "2025-10-24 19:11:50.235000+00:00",
    "id": "8836986f-050c-4b2d-afb9-8069d1520b17",
    "version": { … }
  }
}

Update template

Request

Update a template for a specific domain for the specified service.

Security
BasicAuth or OAuth2
Path
serviceIdstringrequired

The serviceId containing the templates you want to update.

Example: 01GVRB50KEQFFE1SGMPFRNBG6J
domainNamestringrequired

The name of the domain containing the templates you want to update.

Example: yourdomain.com
templateNamestring(TemplateName)required

The name of the template you want to update.

Enum ValueDescription
successful outbound fax

The template for a successful outbound fax.

unsuccessful outbound fax

The template for an unsuccessful outbound fax.

successful inbound fax

The template for a successful inbound fax.

unsuccessful inbound fax

The template for an unsuccessful inbound fax.

Example: successful outbound fax
Bodyapplication/json
templatestring

The contents of the template. The following variables are available for you to use in templates:

VariableDescription
idThe ID of the fax.
fromThe phone number sending the fax.
toThe phone number receiving the fax.
completedTimeThe date and time that the fax was completed.
numberOfPagesThe number of pages included in the fax.
currencyCodeThe currency in which the fax was billed.
amountThe total cost of the fax.
retryCountThe number of times the fax was retried.
Example: "<!DOCTYPE html><html lang='en'><head><meta charset='utf-8'><meta name='viewport' content='width=device-width'></head><body style='margin:0;padding:0;background:#f3f4f6;'><table role='presentation' width='100%' cellpadding='0' cellspacing='0' style='background:#f3f4f6;'><tr><td align='center' style='padding:24px;'><table role='presentation' width='100%' cellpadding='0' cellspacing='0' style='max-width:600px;background:#ffffff;border-radius:8px;border:1px solid #e5e7eb;'><tr><td style='padding:24px 28px;font-family:Segoe UI,Helvetica,Arial,sans-serif;color:#111827;font-size:14px;line-height:1.5;'><p style='margin:0 0 16px 0;'>Hi,</p><p style='margin:0 0 20px 0;'>You have sent a successful fax to: <strong>{{to}}</strong>!</p><table role='presentation' cellpadding='0' cellspacing='0' style='border-collapse:collapse;'><tr><td style='padding:0 10px 6px 0;font-weight:600;'>Fax Id:</td><td style='padding:0 0 6px 0;'>{{id}}</td></tr><tr><td style='padding:0 10px 6px 0;font-weight:600;'>From:</td><td style='padding:0 0 6px 0;'>{{from}}</td></tr><tr><td style='padding:0 10px 6px 0;font-weight:600;'>To:</td><td style='padding:0 0 6px 0;'>{{to}}</td></tr><tr><td style='padding:0 10px 6px 0;font-weight:600;'>Number of pages:</td><td style='padding:0 0 6px 0;'>{{numberOfPages}}</td></tr><tr><td style='padding:0 10px 6px 0;font-weight:600;'>Completed at:</td><td style='padding:0 0 6px 0;'>{{completedTime}}</td></tr><tr><td style='padding:0 10px 0 0;font-weight:600;'>Price:</td><td style='padding:0 0 0 0;'>{{currencyCode}} {{amount}}</td></tr></table><p style='margin:20px 0 0 0;'>Thanks!</p></td></tr></table></td></tr></table></body></html>"
curl -i -X PUT \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/01GVRB50KEQFFE1SGMPFRNBG6J/domains/yourdomain.com/templates/successful outbound fax' \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "<!DOCTYPE html><html lang='\''en'\''><head><meta charset='\''utf-8'\''><meta name='\''viewport'\'' content='\''width=device-width'\''></head><body style='\''margin:0;padding:0;background:#f3f4f6;'\''><table role='\''presentation'\'' width='\''100%'\'' cellpadding='\''0'\'' cellspacing='\''0'\'' style='\''background:#f3f4f6;'\''><tr><td align='\''center'\'' style='\''padding:24px;'\''><table role='\''presentation'\'' width='\''100%'\'' cellpadding='\''0'\'' cellspacing='\''0'\'' style='\''max-width:600px;background:#ffffff;border-radius:8px;border:1px solid #e5e7eb;'\''><tr><td style='\''padding:24px 28px;font-family:Segoe UI,Helvetica,Arial,sans-serif;color:#111827;font-size:14px;line-height:1.5;'\''><p style='\''margin:0 0 16px 0;'\''>Hi,</p><p style='\''margin:0 0 20px 0;'\''>You have sent a successful fax to: <strong>{{to}}</strong>!</p><table role='\''presentation'\'' cellpadding='\''0'\'' cellspacing='\''0'\'' style='\''border-collapse:collapse;'\''><tr><td style='\''padding:0 10px 6px 0;font-weight:600;'\''>Fax Id:</td><td style='\''padding:0 0 6px 0;'\''>{{id}}</td></tr><tr><td style='\''padding:0 10px 6px 0;font-weight:600;'\''>From:</td><td style='\''padding:0 0 6px 0;'\''>{{from}}</td></tr><tr><td style='\''padding:0 10px 6px 0;font-weight:600;'\''>To:</td><td style='\''padding:0 0 6px 0;'\''>{{to}}</td></tr><tr><td style='\''padding:0 10px 6px 0;font-weight:600;'\''>Number of pages:</td><td style='\''padding:0 0 6px 0;'\''>{{numberOfPages}}</td></tr><tr><td style='\''padding:0 10px 6px 0;font-weight:600;'\''>Completed at:</td><td style='\''padding:0 0 6px 0;'\''>{{completedTime}}</td></tr><tr><td style='\''padding:0 10px 0 0;font-weight:600;'\''>Price:</td><td style='\''padding:0 0 0 0;'\''>{{currencyCode}} {{amount}}</td></tr></table><p style='\''margin:20px 0 0 0;'\''>Thanks!</p></td></tr></table></td></tr></table></body></html>"
  }'

Responses

The updated template.

Bodyapplication/json
templateobject

The email template.

Response
application/json
{
  "template": {
    "name": "successful outbound fax",
    "createdAt": "2025-10-24 19:11:50.235000+00:00",
    "id": "8836986f-050c-4b2d-afb9-8069d1520b17",
    "version": { … }
  }
}

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

Error Messages

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