Sign in
latestOpenAPI 3.1.0MIT2026-08-103050171.2 KB

ebcbb377ee0f

Faxes

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.

post/faxes

Request body

tostring phoneNumber required

A phone number in E.164 format, including the leading '+'.

fromstring phoneNumber

A phone number in E.164 format, including the leading '+'.

idstring

The id of a fax

direction'OUTBOUND' | 'INBOUND'

The direction of the fax.

contentUrlstring[]

Multiple URLs

numberOfPagesinteger

The number of pages in the fax.

status'QUEUED' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILURE'

The status of the fax

createTimestring date-time

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

completedTimestring date-time

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

pagesSentSuccessfullyinteger

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

headerTextstring

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.

headerPageNumbersboolean

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

headerTimeZonestring timezone

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

retryDelaySecondsinteger

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

labelsLabels

You can use this to attach labels to your call that you can use in your applications. It is a key value store.

  • application/json format: "labels": {"label1":"value1"}
  • multipart/form-data format: labels[label1] = value1
callbackUrlstring 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.

Note: If a callback URL uses basicauth credentials, when the callback URL is retrieved those credentials are masked. It is not possible to retrieve previously-set credentials through the API.

callbackUrlContentType'multipart/form-data' | 'application/json'

The content type of the callback.

imageConversionMethod'HALFTONE' | 'MONOCHROME'

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.

errorType'DOCUMENT_CONVERSION_ERROR' | 'CALL_ERROR' | 'FAX_ERROR' | 'FATAL_ERROR' | 'GENERAL_ERROR'

Error type

errorCodeinteger

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

errorMessagestring

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

maxRetriesinteger

| 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.

retryCountinteger

The number of times the fax has been retried.

hasFilestring

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

resolution'FINE' | 'SUPERFINE'

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.

coverPageIdstring

The cover page id you want to use for the fax

coverPageDataCoverPageData

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.

  • application/json format: "coverPageData": {"customfield1":"customdata1"}
  • multipart/form-data format: coverPageData[customfield1] = customdata1
inProgressNotificationsboolean

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

projectIdstring

The Id of the project associated with the call.

serviceIdstring

ID of the fax service used.

Example request

{
  "to": "+15551235656",
  "from": "+15551235656",
  "files": [
    {
      "file": "{base64-encoded content}"
    }
  ],
  "id": "01F3J0G1M4WQR6HGY6HCF6JA0K",
  "direction": "OUTBOUND",
  "contentUrl": [
    "www.google.com",
    "www.sinch.com"
  ],
  "price": {
    "currencyCode": "USD",
    "amount": "0.0040"
  },
  "pagesSentSuccessfully": 3,
  "labels": {
    "use-case": "fraudPrevention",
    "costCenter": "sales"
  },
  "callbackUrl": "https://www.my-website.com/callback",
  "coverPageData": {
    "toName": "Acme Corp"
  },
  "projectId": "ae00f005-e392-44dc-b3f5-a657a2684dg3",
  "serviceId": "01GVRB50KEQFFE1SGMPFRNBG6J"
}

Response

The created fax

idstring

The id of a fax

direction'OUTBOUND' | 'INBOUND'

The direction of the fax.

fromstring phoneNumber

A phone number in E.164 format, including the leading '+'.

tostring phoneNumber

A phone number in E.164 format, including the leading '+'.

contentUrlstring[]

Multiple URLs

numberOfPagesinteger

The number of pages in the fax.

status'QUEUED' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILURE'

The status of the fax

createTimestring date-time

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

completedTimestring date-time

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

pagesSentSuccessfullyinteger

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

headerTextstring

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.

headerPageNumbersboolean

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

headerTimeZonestring timezone

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

retryDelaySecondsinteger

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

labelsLabels

You can use this to attach labels to your call that you can use in your applications. It is a key value store.

  • application/json format: "labels": {"label1":"value1"}
  • multipart/form-data format: labels[label1] = value1
callbackUrlstring 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.

Note: If a callback URL uses basicauth credentials, when the callback URL is retrieved those credentials are masked. It is not possible to retrieve previously-set credentials through the API.

callbackUrlContentType'multipart/form-data' | 'application/json'

The content type of the callback.

imageConversionMethod'HALFTONE' | 'MONOCHROME'

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.

errorType'DOCUMENT_CONVERSION_ERROR' | 'CALL_ERROR' | 'FAX_ERROR' | 'FATAL_ERROR' | 'GENERAL_ERROR'

Error type

errorCodeinteger

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

errorMessagestring

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

maxRetriesinteger

| 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.

retryCountinteger

The number of times the fax has been retried.

hasFilestring

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

resolution'FINE' | 'SUPERFINE'

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.

coverPageIdstring

The cover page id you want to use for the fax

coverPageDataCoverPageData

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.

  • application/json format: "coverPageData": {"customfield1":"customdata1"}
  • multipart/form-data format: coverPageData[customfield1] = customdata1
inProgressNotificationsboolean

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

projectIdstring

The Id of the project associated with the call.

serviceIdstring

ID of the fax service used.

Example response

{
  "id": "01F3J0G1M4WQR6HGY6HCF6JA0K",
  "direction": "OUTBOUND",
  "from": "+15551235656",
  "to": "+15551235656",
  "contentUrl": [
    "www.google.com",
    "www.sinch.com"
  ],
  "price": {
    "currencyCode": "USD",
    "amount": "0.0040"
  },
  "pagesSentSuccessfully": 3,
  "labels": {
    "use-case": "fraudPrevention",
    "costCenter": "sales"
  },
  "callbackUrl": "https://www.my-website.com/callback",
  "coverPageData": {
    "toName": "Acme Corp"
  },
  "projectId": "ae00f005-e392-44dc-b3f5-a657a2684dg3",
  "serviceId": "01GVRB50KEQFFE1SGMPFRNBG6J"
}