Skip to content
Fax/
API Reference
/
/
List numbers for 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.

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

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.

Webhooks

You can configure your service to use webhooks to send a request to you when faxes arrive or complete on your account.

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.

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

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

Dashboard

You can manage all your fax services and their settings via the Dashboard.

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

Request

Creates a new service that you can use to set default configuration values.

Security
BasicAuth or OAuth2
Bodyapplication/json
namestring

A friendly name for the service. Maximum is 60 characters.

Default "Default service"
Example: "Default service"
incomingWebhookUrlstring

The URL to which Sinch will post when someone sends a fax to your Sinch number. To accept incoming faxes this must be set and your Sinch phone number must be configured to receive faxes.

Example: "https://yourserver/incomingFax"
webhookContentTypestring

The content type of the webhook.

Default "multipart/form-data"
Enum ValueDescription
multipart/form-data

The webhook will be sent as a multipart/form-data request. Files are sent as attachments to the body.

application/json

The webhook will be sent as a JSON request. Files are sent as base64 encoded strings in the JSON object.

defaultForProjectboolean(string)

If set to true this is the service used to create faxes when no serviceId is specified in the API endpoints.

Default false
defaultFromstring

One of your Sinch numbers connected to this service or any of your verified numbers.

numberOfRetriesinteger

The number of times to retry sending a fax if it fails. Default is 3. Maximum is 5.

Default 3
retryDelaySecondsinteger[ 30 .. 300 ]

The number of seconds to wait between retries if the fax is not yet completed.

Default 60
imageConversionMethodstring(ImageConversionMethod)

Determines how documents are converted to black and white on OUTBOUND faxes only. Image conversion is not done on INBOUND faxes. Defaults to value selected on Fax Service object.

Enum ValueDescription
HALFTONE

Converts the image to halftone.

MONOCHROME

Converts the image to monochrome.

coverPageIdstring(ulid)

If a value it will always add that cover page id to outbound faxes

saveOutboundFaxDocumentsboolean

Save fax documents with Sinch when you send faxes

Default true
saveInboundFaxDocumentsboolean

Save fax documents with Sinch when you receive faxes

Default true
scanIncomingBarcodesboolean

If set to true, barcodes will be detected on incoming faxes.

Default false
inProgressNotificationsboolean

If set to true, you will receive a webhook notification for each page sent on an outbound fax.

Default false
resolutionstring(Resolution)

The resolution for the fax. If this is set at the service, this applies to all faxes sent using that service. If this is set on the fax, this will override the service setting.

Enum ValueDescription
FINE

Most commonly accepted fax resolution at 200 dpi.

SUPERFINE

Higher but less commonly accepted fax resolution at 400 dpi. May be required when sending small text or detailed images.

curl -i -X POST \
  -u <username>:<password> \
  https://fax.api.sinch.com/v3/projects/YOUR_project_id/services \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Default service",
    "incomingWebhookUrl": "https://yourserver/incomingFax",
    "webhookContentType": "multipart/form-data",
    "defaultForProject": false,
    "defaultFrom": "string",
    "numberOfRetries": 3,
    "retryDelaySeconds": 60,
    "imageConversionMethod": "HALFTONE",
    "coverPageId": "string",
    "saveOutboundFaxDocuments": true,
    "saveInboundFaxDocuments": true,
    "scanIncomingBarcodes": false,
    "inProgressNotifications": false,
    "resolution": "FINE"
  }'

Responses

The newly created service

Bodyapplication/json
idstring(ServiceId)read-only

ID of the fax service used.

namestring

A friendly name for the service. Maximum is 60 characters.

Default "Default service"
Example: "Default service"
incomingWebhookUrlstring

The URL to which Sinch will post when someone sends a fax to your Sinch number. To accept incoming faxes this must be set and your Sinch phone number must be configured to receive faxes.

Example: "https://yourserver/incomingFax"
webhookContentTypestring

The content type of the webhook.

Default "multipart/form-data"
Enum ValueDescription
multipart/form-data

The webhook will be sent as a multipart/form-data request. Files are sent as attachments to the body.

application/json

The webhook will be sent as a JSON request. Files are sent as base64 encoded strings in the JSON object.

defaultForProjectboolean(string)

If set to true this is the service used to create faxes when no serviceId is specified in the API endpoints.

Default false
defaultFromstring

One of your Sinch numbers connected to this service or any of your verified numbers.

numberOfRetriesinteger

The number of times to retry sending a fax if it fails. Default is 3. Maximum is 5.

Default 3
retryDelaySecondsinteger[ 30 .. 300 ]

The number of seconds to wait between retries if the fax is not yet completed.

Default 60
imageConversionMethodstring(ImageConversionMethod)

Determines how documents are converted to black and white on OUTBOUND faxes only. Image conversion is not done on INBOUND faxes. Defaults to value selected on Fax Service object.

Enum ValueDescription
HALFTONE

Converts the image to halftone.

MONOCHROME

Converts the image to monochrome.

coverPageIdstring(ulid)

If a value it will always add that cover page id to outbound faxes

saveOutboundFaxDocumentsboolean

Save fax documents with Sinch when you send faxes

Default true
saveInboundFaxDocumentsboolean

Save fax documents with Sinch when you receive faxes

Default true
scanIncomingBarcodesboolean

If set to true, barcodes will be detected on incoming faxes.

Default false
inProgressNotificationsboolean

If set to true, you will receive a webhook notification for each page sent on an outbound fax.

Default false
projectIdstring(ProjectId)read-only

The Id of the project associated with the call.

resolutionstring(Resolution)

The resolution for the fax. If this is set at the service, this applies to all faxes sent using that service. If this is set on the fax, this will override the service setting.

Enum ValueDescription
FINE

Most commonly accepted fax resolution at 200 dpi.

SUPERFINE

Higher but less commonly accepted fax resolution at 400 dpi. May be required when sending small text or detailed images.

Response
application/json
{
  "id": "01GVRB50KEQFFE1SGMPFRNBG6J",
  "name": "Default service",
  "incomingWebhookUrl": "https://yourserver/incomingFax",
  "webhookContentType": "multipart/form-data",
  "defaultForProject": false,
  "defaultFrom": "string",
  "numberOfRetries": 3,
  "retryDelaySeconds": 60,
  "imageConversionMethod": "HALFTONE",
  "coverPageId": "string",
  "saveOutboundFaxDocuments": true,
  "saveInboundFaxDocuments": true,
  "scanIncomingBarcodes": false,
  "inProgressNotifications": false,
  "projectId": "ae00f005-e392-44dc-b3f5-a657a2684dg3",
  "resolution": "FINE"
}

List services

Request

Get a list of services for a project.

Security
BasicAuth or OAuth2
Query
pageSizeinteger<= 1000

Number of services to return on each request.

Default 20
Example: pageSize=20
pagestring

Optional. The page to fetch. If not specified, the first page will be returned.

curl -i -X GET \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services?pageSize=20&page=string'

Responses

List of services, or an Error

Bodyapplication/json
servicesArray of objects(Service)

List of services.

pageintegerread-only

Current page

totalPagesintegerread-only

Total number of pages.

pageSizeintegerread-only

Number of items per page.

totalItemsinteger(int32)read-only

Total size of the result.

Response
application/json
{
  "services": [
    { … }
  ],
  "page": 0,
  "totalPages": 0,
  "pageSize": 0,
  "totalItems": 0
}

Get a service

Request

Get a service resource.

Security
BasicAuth or OAuth2
Path
idstringrequired

The service ID you want to update.

curl -i -X GET \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}'

Responses

The requested service, or an Error

Bodyapplication/json
idstring(ServiceId)read-only

ID of the fax service used.

namestring

A friendly name for the service. Maximum is 60 characters.

Default "Default service"
Example: "Default service"
incomingWebhookUrlstring

The URL to which Sinch will post when someone sends a fax to your Sinch number. To accept incoming faxes this must be set and your Sinch phone number must be configured to receive faxes.

Example: "https://yourserver/incomingFax"
webhookContentTypestring

The content type of the webhook.

Default "multipart/form-data"
Enum ValueDescription
multipart/form-data

The webhook will be sent as a multipart/form-data request. Files are sent as attachments to the body.

application/json

The webhook will be sent as a JSON request. Files are sent as base64 encoded strings in the JSON object.

defaultForProjectboolean(string)

If set to true this is the service used to create faxes when no serviceId is specified in the API endpoints.

Default false
defaultFromstring

One of your Sinch numbers connected to this service or any of your verified numbers.

numberOfRetriesinteger

The number of times to retry sending a fax if it fails. Default is 3. Maximum is 5.

Default 3
retryDelaySecondsinteger[ 30 .. 300 ]

The number of seconds to wait between retries if the fax is not yet completed.

Default 60
imageConversionMethodstring(ImageConversionMethod)

Determines how documents are converted to black and white on OUTBOUND faxes only. Image conversion is not done on INBOUND faxes. Defaults to value selected on Fax Service object.

Enum ValueDescription
HALFTONE

Converts the image to halftone.

MONOCHROME

Converts the image to monochrome.

coverPageIdstring(ulid)

If a value it will always add that cover page id to outbound faxes

saveOutboundFaxDocumentsboolean

Save fax documents with Sinch when you send faxes

Default true
saveInboundFaxDocumentsboolean

Save fax documents with Sinch when you receive faxes

Default true
scanIncomingBarcodesboolean

If set to true, barcodes will be detected on incoming faxes.

Default false
inProgressNotificationsboolean

If set to true, you will receive a webhook notification for each page sent on an outbound fax.

Default false
projectIdstring(ProjectId)read-only

The Id of the project associated with the call.

resolutionstring(Resolution)

The resolution for the fax. If this is set at the service, this applies to all faxes sent using that service. If this is set on the fax, this will override the service setting.

Enum ValueDescription
FINE

Most commonly accepted fax resolution at 200 dpi.

SUPERFINE

Higher but less commonly accepted fax resolution at 400 dpi. May be required when sending small text or detailed images.

Response
application/json
{
  "id": "01GVRB50KEQFFE1SGMPFRNBG6J",
  "name": "Default service",
  "incomingWebhookUrl": "https://yourserver/incomingFax",
  "webhookContentType": "multipart/form-data",
  "defaultForProject": false,
  "defaultFrom": "string",
  "numberOfRetries": 3,
  "retryDelaySeconds": 60,
  "imageConversionMethod": "HALFTONE",
  "coverPageId": "string",
  "saveOutboundFaxDocuments": true,
  "saveInboundFaxDocuments": true,
  "scanIncomingBarcodes": false,
  "inProgressNotifications": false,
  "projectId": "ae00f005-e392-44dc-b3f5-a657a2684dg3",
  "resolution": "FINE"
}

Update a Service

Request

Update settings on the service.

Security
BasicAuth or OAuth2
Path
idstringrequired

The service ID you want to update.

Bodyapplication/json
namestring

A friendly name for the service. Maximum is 60 characters.

Default "Default service"
Example: "Default service"
incomingWebhookUrlstring

The URL to which Sinch will post when someone sends a fax to your Sinch number. To accept incoming faxes this must be set and your Sinch phone number must be configured to receive faxes.

Example: "https://yourserver/incomingFax"
webhookContentTypestring

The content type of the webhook.

Default "multipart/form-data"
Enum ValueDescription
multipart/form-data

The webhook will be sent as a multipart/form-data request. Files are sent as attachments to the body.

application/json

The webhook will be sent as a JSON request. Files are sent as base64 encoded strings in the JSON object.

defaultForProjectboolean(string)

If set to true this is the service used to create faxes when no serviceId is specified in the API endpoints.

Default false
defaultFromstring

One of your Sinch numbers connected to this service or any of your verified numbers.

numberOfRetriesinteger

The number of times to retry sending a fax if it fails. Default is 3. Maximum is 5.

Default 3
retryDelaySecondsinteger[ 30 .. 300 ]

The number of seconds to wait between retries if the fax is not yet completed.

Default 60
imageConversionMethodstring(ImageConversionMethod)

Determines how documents are converted to black and white on OUTBOUND faxes only. Image conversion is not done on INBOUND faxes. Defaults to value selected on Fax Service object.

Enum ValueDescription
HALFTONE

Converts the image to halftone.

MONOCHROME

Converts the image to monochrome.

coverPageIdstring(ulid)

If a value it will always add that cover page id to outbound faxes

saveOutboundFaxDocumentsboolean

Save fax documents with Sinch when you send faxes

Default true
saveInboundFaxDocumentsboolean

Save fax documents with Sinch when you receive faxes

Default true
scanIncomingBarcodesboolean

If set to true, barcodes will be detected on incoming faxes.

Default false
inProgressNotificationsboolean

If set to true, you will receive a webhook notification for each page sent on an outbound fax.

Default false
resolutionstring(Resolution)

The resolution for the fax. If this is set at the service, this applies to all faxes sent using that service. If this is set on the fax, this will override the service setting.

Enum ValueDescription
FINE

Most commonly accepted fax resolution at 200 dpi.

SUPERFINE

Higher but less commonly accepted fax resolution at 400 dpi. May be required when sending small text or detailed images.

curl -i -X PATCH \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Default service",
    "incomingWebhookUrl": "https://yourserver/incomingFax",
    "webhookContentType": "multipart/form-data",
    "defaultForProject": false,
    "defaultFrom": "string",
    "numberOfRetries": 3,
    "retryDelaySeconds": 60,
    "imageConversionMethod": "HALFTONE",
    "coverPageId": "string",
    "saveOutboundFaxDocuments": true,
    "saveInboundFaxDocuments": true,
    "scanIncomingBarcodes": false,
    "inProgressNotifications": false,
    "resolution": "FINE"
  }'

Responses

The updated service, or an Error

Bodyapplication/json
idstring(ServiceId)read-only

ID of the fax service used.

namestring

A friendly name for the service. Maximum is 60 characters.

Default "Default service"
Example: "Default service"
incomingWebhookUrlstring

The URL to which Sinch will post when someone sends a fax to your Sinch number. To accept incoming faxes this must be set and your Sinch phone number must be configured to receive faxes.

Example: "https://yourserver/incomingFax"
webhookContentTypestring

The content type of the webhook.

Default "multipart/form-data"
Enum ValueDescription
multipart/form-data

The webhook will be sent as a multipart/form-data request. Files are sent as attachments to the body.

application/json

The webhook will be sent as a JSON request. Files are sent as base64 encoded strings in the JSON object.

defaultForProjectboolean(string)

If set to true this is the service used to create faxes when no serviceId is specified in the API endpoints.

Default false
defaultFromstring

One of your Sinch numbers connected to this service or any of your verified numbers.

numberOfRetriesinteger

The number of times to retry sending a fax if it fails. Default is 3. Maximum is 5.

Default 3
retryDelaySecondsinteger[ 30 .. 300 ]

The number of seconds to wait between retries if the fax is not yet completed.

Default 60
imageConversionMethodstring(ImageConversionMethod)

Determines how documents are converted to black and white on OUTBOUND faxes only. Image conversion is not done on INBOUND faxes. Defaults to value selected on Fax Service object.

Enum ValueDescription
HALFTONE

Converts the image to halftone.

MONOCHROME

Converts the image to monochrome.

coverPageIdstring(ulid)

If a value it will always add that cover page id to outbound faxes

saveOutboundFaxDocumentsboolean

Save fax documents with Sinch when you send faxes

Default true
saveInboundFaxDocumentsboolean

Save fax documents with Sinch when you receive faxes

Default true
scanIncomingBarcodesboolean

If set to true, barcodes will be detected on incoming faxes.

Default false
inProgressNotificationsboolean

If set to true, you will receive a webhook notification for each page sent on an outbound fax.

Default false
projectIdstring(ProjectId)read-only

The Id of the project associated with the call.

resolutionstring(Resolution)

The resolution for the fax. If this is set at the service, this applies to all faxes sent using that service. If this is set on the fax, this will override the service setting.

Enum ValueDescription
FINE

Most commonly accepted fax resolution at 200 dpi.

SUPERFINE

Higher but less commonly accepted fax resolution at 400 dpi. May be required when sending small text or detailed images.

Response
application/json
{
  "id": "01GVRB50KEQFFE1SGMPFRNBG6J",
  "name": "Default service",
  "incomingWebhookUrl": "https://yourserver/incomingFax",
  "webhookContentType": "multipart/form-data",
  "defaultForProject": false,
  "defaultFrom": "string",
  "numberOfRetries": 3,
  "retryDelaySeconds": 60,
  "imageConversionMethod": "HALFTONE",
  "coverPageId": "string",
  "saveOutboundFaxDocuments": true,
  "saveInboundFaxDocuments": true,
  "scanIncomingBarcodes": false,
  "inProgressNotifications": false,
  "projectId": "ae00f005-e392-44dc-b3f5-a657a2684dg3",
  "resolution": "FINE"
}

Remove a service

Request

Removes a service from your project.

Security
BasicAuth or OAuth2
Path
idstringrequired

The serviceId you want to remove from your project.

curl -i -X DELETE \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}'

Responses

The service removed from the project, or an Error

List numbers for service

Request

List numbers for a service.

Security
BasicAuth or OAuth2
Path
idstringrequired

The serviceId containing the numbers you want to list.

Query
pageSizeinteger<= 1000

Number of items to return on each page.

Default 20
Example: pageSize=20
pagestring

Optional. The page to fetch. If not specified, the first page will be returned.

curl -i -X GET \
  -u <username>:<password> \
  'https://fax.api.sinch.com/v3/projects/YOUR_project_id/services/{id}/numbers?pageSize=20&page=string'

Responses

The list of numbers, or an Error

Bodyapplication/json
numbersArray of objects(ServicePhoneNumber)

List of phone numbers

pageintegerread-only

Current page

totalPagesintegerread-only

Total number of pages.

pageSizeintegerread-only

Number of items per page.

totalItemsinteger(int32)read-only

Total size of the result.

Response
application/json
{
  "numbers": [
    { … }
  ],
  "page": 0,
  "totalPages": 0,
  "pageSize": 0,
  "totalItems": 0
}