Download OpenAPI specification:Download

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

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.

SecurityBasicAuth or OAuth2
Request
Request Body schema:
to
required
string <phoneNumber>

When you send a fax you can specify a single number or a list of numbers separated by ;. Please note that if you specify a list of numbers, the fax will be sent to all numbers and a Fax resource will be created for each number.

When you receive a fax, this is the number where the fax is sent to.

file
string <binary>

The file(s) you want to send as a fax as body attachment.

from
string <phoneNumber>

For INBOUND faxes, this is the number where the fax is sent from For OUTBOUND faxes, this is the Sinch number you want to have as sender

string or Array of strings <URL>

Give us any URL on the Internet (including ones with basic authentication) At least one file or contentUrl parameter is required. 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. If the file parameter is specified as well, content from URLs will be rendered before content from files.

You can add multiple URLs by adding them as an array them with a comma when posting as multipart/form-data

For example: "https://developers.sinch.com/fax/fax.pdf, https://developers.sinch.com/" or if posting JSON "contentUrl": ["https://developers.sinch.com/fax/fax.pdf", "https://developers.sinch.com/"]

headerText
string <= 50
Default: ""

Text that will be displayed at the top of each page of the fax. 50 characters maximum. Default header text is "-". Note that the header is not applied until the fax is transmitted, so it will not appear on fax PDFs or thumbnails.

headerPageNumbers
boolean
Default: true

If true, page numbers will be displayed in the header. Default is true.

headerTimeZone
string <timezone>
Default: "America/New_York"

A TZ database name string specifying the timezone for the header timestamp.

retryDelaySeconds
integer [ 30 .. 300 ]
Default: 60

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

object (label)

You can use this to attach labels to your call that you can use in your BI solutions.

callbackUrl
string <URL>

The URL to which a callback will be sent when the fax is completed. The callback will be sent as a POST request with a JSON body. The callback will be sent to the URL specified in the callbackUrl parameter, if provided, otherwise it will be sent to the URL specified in the callbackUrl field of the Fax Service object.

callbackUrlContentType
string
Default: "multipart/form-data"

The content type of the callback.

Enum Value Description
multipart/form-data

The callback will be sent as a multipart/form-data request with files as attachments to the body.

application/json

The callback will be sent as a JSON request with the files as base64 encoded strings in the JSON object.

imageConversionMethod
string
Default: "HALFTONE"

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: "HALFTONE" "MONOCHROME"
maxRetries
integer [ 0 .. 5 ]

| The number of times the fax will be retired before cancel. Default value is set in your fax service. | The maximum number of retries is 5.

resolution
string (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 Value Description
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.

coverPageId
string

The cover page id you want to use for the fax

object (CoverPageData)

You can use this to specify custom data for your cover page that will be sent as part of the fax. It is a key value store. Read more about how to use this here. All keys used must be lower case.

serviceId
string

ID of the fax service used.

Responses
200

The created fax

Response Schema: application/json
id
string

The id of a fax

direction
string

The direction of the fax.

Enum Value Description
OUTBOUND

The fax was sent by you via the api.

INBOUND

The fax was received on one of your numbers.

from
string <phoneNumber>

For INBOUND faxes, this is the number where the fax is sent from For OUTBOUND faxes, this is the Sinch number you want to have as sender

to
string <phoneNumber>

For INBOUND faxes, this is the Sinch number someone sent the fax to. For OUTBOUND faxes, this is the phone number you want to send a fax to.

You can add multiple numbers by adding them as an array. For example:

application/json

"to": ["+14155552222", "+14155553333"]

multipart/form

to=+14155552222&to=+14155553333
numberOfPages
integer

The number of pages in the fax.

status
string (FaxStatus)

The status of the fax

Enum Value Description
QUEUED

The operation is currently in a queue on a server and should be executed very soon.

IN_PROGRESS

The fax is currently being sent (OUTBOUND) or received (INBOUND).

COMPLETED

The fax operation succeeded. Everything went as normally planned.

FAILURE

The fax operation failed. Details of the error can be found in the error_code field. For OUTBOUND fax, this means that NONE of the recipients received the fax.

object

The total price for this fax. This field is populated after the final fax price is calculated.

Array of objects (BarCode)

The bar codes found in the fax. This field is populated when sinch detects bar codes on incoming faxes.

createTime
string <date-time>

A timestamp representing the time when the initial API call was made.

completedTime
string <date-time>

If the job is complete, this is a timestamp representing the time the job was completed.

pagesSentSuccessfully
integer

The number of pages successfully sent to the receiving side in the fax.

headerText
string <= 50
Default: ""

Text that will be displayed at the top of each page of the fax. 50 characters maximum. Default header text is "-". Note that the header is not applied until the fax is transmitted, so it will not appear on fax PDFs or thumbnails.

headerPageNumbers
boolean
Default: true

If true, page numbers will be displayed in the header. Default is true.

headerTimeZone
string <timezone>
Default: "America/New_York"

A TZ database name string specifying the timezone for the header timestamp.

retryDelaySeconds
integer [ 30 .. 300 ]
Default: 60

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

object (label)

You can use this to attach labels to your call that you can use in your BI solutions.

callbackUrl
string <URL>

The URL to which a callback will be sent when the fax is completed. The callback will be sent as a POST request with a JSON body. The callback will be sent to the URL specified in the callbackUrl parameter, if provided, otherwise it will be sent to the URL specified in the callbackUrl field of the Fax Service object.

callbackUrlContentType
string
Default: "multipart/form-data"

The content type of the callback.

Enum Value Description
multipart/form-data

The callback will be sent as a multipart/form-data request with files as attachments to the body.

application/json

The callback will be sent as a JSON request with the files as base64 encoded strings in the JSON object.

imageConversionMethod
string
Default: "HALFTONE"

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: "HALFTONE" "MONOCHROME"
errorType
string

Error type

Enum: "DOCUMENT_CONVERSION_ERROR" "CALL_ERROR" "FAX_ERROR" "FATAL_ERROR" "GENERAL_ERROR"
errorCode
integer

One of the error numbers listed in the Fax Error Messages section.

errorMessage
string

One of the error codes listed in the Fax Error Messages section.

maxRetries
integer [ 0 .. 5 ]

| The number of times the fax will be retired before cancel. Default value is set in your fax service. | The maximum number of retries is 5.

retryCount
integer

The number of times the fax has been retried.

hasFile
string

Only shown on the fax result. This indicates if the content of the fax is stored with Sinch. (true or false)

resolution
string (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 Value Description
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.

coverPageId
string

The cover page id you want to use for the fax

object (CoverPageData)

You can use this to specify custom data for your cover page that will be sent as part of the fax. It is a key value store. Read more about how to use this here. All keys used must be lower case.

projectId
string

The Id of the project associated with the call.

serviceId
string

ID of the fax service used.

post/faxes
Request samples 
{
  "to": "+14155552222",
  "contentUrl": "https://developers.sinch.com/fax/fax.pdf"
}
Response samples
application/json
{
  • "id": "01HDF5S9P29WC29J578J8EKC1C",
  • "direction": "OUTBOUND",
  • "to": "+1234567890",
  • "status": "IN_PROGRESS",
  • "headerTimeZone": "America/New_York",
  • "retryDelaySeconds": 60,
  • "callbackUrl": "https://my.callback.server",
  • "projectId": "YOUR_PROJECT_ID",
  • "serviceId": "YOUR_SERVICE_ID",
  • "maxRetries": 3,
  • "createTime": "2023-10-23T21:06:52.231Z",
  • "headerPageNumbers": true,
  • "contentUrl": [
    • "www.google.com"
    ],
  • "imageConversionMethod": "HALFTONE"
}

List faxes

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
SecurityBasicAuth or OAuth2
Request
query Parameters
serviceId
string

Limits results to faxes that were sent using the specified service.

Example: serviceId=YOUR_SERVICE_ID
createTime
string <date-time>

Filter calls based on createTime. If you make the query more precise, fewer results will be returned. For example, 2021-02-01 will return all calls from the first of February 2021, and 2021-02-01T14:00:00Z will return all calls after 14:00 on the first of February. This field also supports <= and >= to search for calls in a range ?createTime>=2021-10-01&startTime<=2021-10-30 to get a list of calls for all of October 2021. It is also possible to submit partial dates. For example, createTime=2021-02 will return all calls for February 2021.

If not value is submitted, the default value is the prior week.

Example: createTime=2021-11-01T23:25:67Z
direction
string (FaxDirection)

Limits results to faxes with the specified direction.

Enum Value Description
OUTBOUND

The fax was sent by you via the api.

INBOUND

The fax was received on one of your numbers.

Example: direction=OUTBOUND
status
string (FaxStatus)

Limits results to faxes with the specified status.

Enum Value Description
QUEUED

The operation is currently in a queue on a server and should be executed very soon.

IN_PROGRESS

The fax is currently being sent (OUTBOUND) or received (INBOUND).

COMPLETED

The fax operation succeeded. Everything went as normally planned.

FAILURE

The fax operation failed. Details of the error can be found in the error_code field. For OUTBOUND fax, this means that NONE of the recipients received the fax.

Example: status=COMPLETED
to
string <phoneNumber> (PhoneNumber)

A phone number that you want to use to filter results. The parameter search with startsWith, so you can pass a partial number to get all faxes sent to numbers that start with the number you passed.

Example: to=+14155552222
from
string <phoneNumber> (PhoneNumber)

A phone number that you want to use to filter results. The parameter search with startsWith, so you can pass a partial number to get all faxes sent to numbers that start with the number you passed.

Example: from=+15551235656
pageSize
integer [ 1 .. 1000 ]

The maximum number of items to return per request. The default is 100 and the maximum is 1000. If you need to export larger amounts and pagination is not suitable for you can use the Export function in the dashboard.

page
string

The page you want to retrieve returned from a previous List request, if any

Responses
200

Result of the query.

Response Schema: application/json
Array of objects (Fax)

An array of faxes

page
integer

Current page

totalPages
integer

Total number of pages.

pageSize
integer

Number of items per page.

totalItems
integer <int32>

Total size of the result.

get/faxes
Request samples 
Response samples 
application/json
{
  • "faxes": [
    • {
      }
    ],
  • "page": 0,
  • "totalPages": 0,
  • "pageSize": 0,
  • "totalItems": 0
}
Get fax
Get fax information using the ID number of the fax.


SecurityBasicAuth or OAuth2 
Request 
path Parameters
id
required
string (FaxId) 
The ID of the fax.


 
 Example:  01F3J0G1M4WQR6HGY6HCF6JA0K
Responses 
200
The fax


Response Schema: application/json
id
string
The id of a fax


 
direction
string
The direction of the fax.


 Enum Value Description
OUTBOUND
The fax was sent by you via the api.


INBOUND
The fax was received on one of your numbers.


 
from
string <phoneNumber> 
For INBOUND faxes, this is the number where the fax is sent from
For OUTBOUND faxes, this is the Sinch number you want to have as sender


 
to
string <phoneNumber> 
For INBOUND faxes, this is the Sinch number someone sent the fax to.
For OUTBOUND faxes, this is the phone number you want to send a fax to.


You can add multiple numbers by adding them as an array. For example:


  application/json


"to": ["+14155552222", "+14155553333"]



  multipart/form


to=+14155552222&to=+14155553333



 
numberOfPages
integer
The number of pages in the fax.


 
status
string (FaxStatus) 
The status of the fax


 Enum Value Description
QUEUED
The operation is currently in a queue on a server and should be executed very soon.


IN_PROGRESS
The fax is currently being sent (OUTBOUND) or received (INBOUND).


COMPLETED
The fax operation succeeded. Everything went as normally planned.


FAILURE
The fax operation failed. Details of the error can be found in the error_code field. For OUTBOUND fax, this means that NONE of the recipients received the fax.


 
object
The total price for this fax. This field is populated after the final fax price is calculated.


 
Array of objects (BarCode) 
The bar codes found in the fax. This field is populated when sinch detects bar codes on incoming faxes.


 
createTime
string <date-time> 
A timestamp representing the time when the initial API call was made.


 
completedTime
string <date-time> 
If the job is complete, this is a timestamp representing the time the job was completed.


 
pagesSentSuccessfully
integer
The number of pages successfully sent to the receiving side in the fax.


 
headerText
string  <= 50 
 Default:  ""
Text that will be displayed at the top of each page of the fax. 50 characters maximum. Default header text is "-". Note that the header is not applied until the fax is transmitted, so it will not appear on fax PDFs or thumbnails.


 
headerPageNumbers
boolean
 Default:  true
If true, page numbers will be displayed in the header. Default is true.


 
headerTimeZone
string <timezone> 
 Default:  "America/New_York"
A TZ database name string specifying the timezone for the header timestamp.


 
retryDelaySeconds
integer  [ 30 .. 300 ] 
 Default:  60
The number of seconds to wait between retries if the fax is not yet completed.


 
object (label) 
You can use this to attach labels to your call that you can use in your BI solutions.


 
callbackUrl
string <URL> 
The URL to which a callback will be sent when the fax is completed. The callback will be sent as a POST request with a JSON body. The callback will be sent to the URL specified in the callbackUrl parameter, if provided, otherwise it will be sent to the URL specified in the callbackUrl field of the Fax Service object.


 
callbackUrlContentType
string
 Default:  "multipart/form-data"
The content type of the callback.


 Enum Value Description
multipart/form-data
The callback will be sent as a multipart/form-data request with files as attachments to the body.


application/json
The callback will be sent as a JSON request with the files as base64 encoded strings in the JSON object.


 
imageConversionMethod
string
 Default:  "HALFTONE"
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: "HALFTONE" "MONOCHROME"  
errorType
string
Error type


 Enum: "DOCUMENT_CONVERSION_ERROR" "CALL_ERROR" "FAX_ERROR" "FATAL_ERROR" "GENERAL_ERROR"  
errorCode
integer
One of the error numbers listed in the Fax Error Messages section.


 
errorMessage
string
One of the error codes listed in the Fax Error Messages section.


 
maxRetries
integer  [ 0 .. 5 ] 
| The number of times the fax will be retired before cancel. Default value is set in your fax service.
| The maximum number of retries is 5.


 
retryCount
integer
The number of times the fax has been retried.


 
hasFile
string
Only shown on the fax result. This indicates if the content of the fax is stored with Sinch. (true or false)


 
resolution
string (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 Value Description
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.


 
coverPageId
string
The cover page id you want to use for the fax


 
object (CoverPageData) 
You can use this to specify custom data for your cover page that will be sent as part of the fax. It is a key value store. Read more about how to use this here. All keys used must be lower case.


 
projectId
string
The Id of the project associated with the call.


 
serviceId
string
ID of the fax service used.


 
get/faxes/{id}
Request samples 
Response samples 
application/json
{
  • "id": "01HDF5S9P29WC29J578J8EKC1C",
  • "direction": "OUTBOUND",
  • "to": "+1234567890",
  • "status": "IN_PROGRESS",
  • "headerTimeZone": "America/New_York",
  • "retryDelaySeconds": 60,
  • "callbackUrl": "https://my.callback.server",
  • "projectId": "YOUR_PROJECT_ID",
  • "serviceId": "YOUR_SERVICE_ID",
  • "maxRetries": 3,
  • "createTime": "2023-10-23T21:06:52.231Z",
  • "headerPageNumbers": true,
  • "contentUrl": [
    • "www.google.com"
    ],
  • "imageConversionMethod": "HALFTONE",
  • "hasFile": false
}
Delete fax content
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.


SecurityBasicAuth or OAuth2 
Request 
path Parameters
id
required
string (FaxId) 
The ID of the fax.


 
 Example:  01F3J0G1M4WQR6HGY6HCF6JA0K
Responses 
204
The fax content was deleted.


delete/faxes/{id}/file
Request samples 
Download fax content
Download the fax content.


SecurityBasicAuth or OAuth2 
Request 
path Parameters
id
required
string (FaxId) 
The ID of the fax.


 
 Example:  01F3J0G1M4WQR6HGY6HCF6JA0K
fileFormat
required
string
 Default:  "pdf"
The file format to download. Currently only PDF is supported.


 Value Description
pdf
PDF format


 
 Example:  pdf
Responses 
200
A file for the fax you requested will be returned in the format you specified.


Response Schema: application/pdf
string <binary> 
A PDF file named 'fax-1234.pdf' containing all files sent for fax #1234.


 
get/faxes/{id}/file.{fileFormat}
Request samples 
Incoming fax eventWebhook 
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.


SecurityBasicAuth 
Request 
Request Body schema: 
event
string
 Default:  "INCOMING_FAX"
The value is always INCOMING_FAX for this event.


 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.


 
file
string <binary>  <binary>  <application/pdf> 
The fax content as a PDF attachment to the body


 
eventTime
string <date-time> 
Time of the event.


 
object (Fax) 
 
Responses 
200
Returns a 200 OK response if the webhook was received successfully.


Request samples 
{
  "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}"
}
Fax completedWebhook 
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.


SecurityBasicAuth 
Request 
Request Body schema: 
event
string
 Default:  "FAX_COMPLETED"
Always fax completed for this event.


 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.


 
file
string <binary>  <binary>  <application/pdf> 
The fax content as pdf attachment to the body


 
eventTime
string <date-time> 
Time of the event.


 
object (Fax) 
 
Responses 
200
Returns a 200 OK response if the webhook was received successfully.


Request samples 
{
  "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}"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.