{
"openapi": "3.1.0",
"info": {
"version": "3.0",
"title": "Fax API",
"description": "This document provides a detailed user guide and reference documentation on the Fax REST API.\n\nIf you have questions please contact us via our [support portal](https://support.sinch.com) and a team member will be happy to assist.\n\n{% admonition type=\"info\" name=\"Note:\" %}\nYou must create an account on our support portal if you do not have one.\n{% /admonition %}\n\n## Authentication\n\nFor information on how to authenticate API requests we support two methods [Basic](https://developers.sinch.com/docs/fax/api-reference/authentication/basic) or [Oauth2](https://developers.sinch.com/docs/fax/api-reference/authentication/oauth)\n\n## Global URL\n\nSinch has a global server that will route your call to the appropriate geography region automatically:\n\n```shell\nhttps://fax.api.sinch.com/\n```\n\n## Formats\n\nBy default, all API calls return a JSON response unless otherwise specified.\n\n### Date time fields\n\nAll date and time fields are in UTC format unless otherwise specified.\n\n## Deletion and data retention\n\nIf 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.\n\n## Errors & statuses\n\nFind error codes and explanations [here](https://developers.sinch.com/docs/fax/api-reference/fax/error-messages).\n\n## Webhooks\n\nYou can configure your service to use webhooks to send a request to you when faxes arrive or complete on your account.\n",
"contact": {
"name": "Contact Fax API Team",
"url": "https://www.sinch.com/contact/",
"email": "faxteam@sinch.com"
},
"license": {
"url": "https://www.sinch.com/toc",
"name": "MIT"
}
},
"servers": [
{
"url": "https://fax.api.sinch.com/v3/projects/{projectId}",
"description": "v3.0 of the Fax API",
"variables": {
"projectId": {
"description": "The project with which you are working.",
"default": "YOUR_project_id"
}
}
}
],
"security": [
{
"BasicAuth": []
},
{
"OAuth2": []
}
],
"tags": [
{
"name": "Faxes",
"description": "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.\n\nTo 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."
},
{
"name": "Notifications",
"description": "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.\nHTTP webhooks are multipart/form-data POST requests, and should be processed like form submissions.\n\n## Setting up webhooks\n\nDepending on the type of webhook, you can configure the callback URLs in a few ways:\n\n **Incoming fax notification**:\n\n - On your [Fax service](https://dashboard.sinch.com/fax/services) in the dashboard.\n - Using the [API when configuring your service](https://developers.sinch.com/docs/fax/api-reference/fax/services/createnotificationwebhook). This is required to receive notifications about incoming calls to your Sinch number.\n\n **Fax completed notification**:\n\n - By including the `callbackUrl` property in the request body when you send a fax via the `/faxes` endpoint.\n\n### Retries\n\nIf a webhook fails, we will automatically retry sending the fax up to 16 times. There will be a delay before each retry, which increases as follows:\n\n| Retry number | Delay | Cumulative wait |\n| ------------ | ---------- | ------------ |\n| 1 | 5 minutes | 5 minutes |\n| 2 | 10 minutes | 15 minutes |\n| 3 | 20 minutes | 35 minutes |\n| 4 | 30 minutes | 1 hour 5 minutes |\n| 5-16 | 6 hours | up to ~3 days |\n\n### IP Addresses\n\nNotifications are sent from the following IP addresses so you can add them to allowlists if necessary.\n\n| IP address | Description |\n| ---------- | ----------- |\n| 34.232.249.173 | use1 (East) |\n| 44.226.9.173 | usw2 (West) |"
},
{
"name": "Fax to Email",
"description": "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.\nThe service supports sending incoming faxes to multiple email addresses and having many numbers associated with one email address.\n\n## Setting up fax to email\n\nYou can configure fax to email in two different places:\n\n - In the dashboard on a number-by-number basis or by adding an email address and associating many numbers to one email address.\n - Via the API when you create a number or update a number, or by using the email endpoint to set it up directly\n - Supported fax to email file types are Word, PDF, and TIF\n\n## Fax to email example\n\nThe following example shows how to configure Fax to Email using the API:\n 1. Buy a number in the dashboard and assign it to a Fax service\n 2. Add your email and associate it with the number you bought in step 1.\n\n```json\nPOST https://fax.api.sinch.com/v3/projects/{projectId}/services/{serviceId}/emails\n {\n \"email\": \"user@domain.com\",\n \"phoneNumbers\": [\n \"+14155552222\"\n ]\n}\n```\nNow you can use your email client with the above email address to fax.\n\n## Send a fax using email\n\nMake sure the email address you are sending from is added to your account. You can add it in the dashboard under [Fax to email](https://dashboard.sinch.com/fax/fax-to-email) or via the API.\n\nSend an email to {PhoneNumberToSendFaxTo}@sinchfax.com with the following:\n\n| Field | Description |\n| ----- | ----------- |\n| **Subject:** | If you have multiple phone numbers associated with the email address, enter the number you want to use. If left blank, the first number that we find will be used. |\n| **Body:** | By default, the email body is not used. |\n| **Attachments** | Add any attachments you want to fax. If you want to specify the order of pages we recommend that you create one document with all pages in the correct order and attach that document. If you attach multiple documents we will merge them into one document in the order we receive them. |\n\n\n## Receive a fax using email\n\nWhen you receive a fax, we will send you an email with the following:\n| Field | Description |\n| ----- | ----------- |\n| **From:** | The number the fax was sent from, e.g. +15612600684@sinchfax.com |\n| **Subject:** | Fax received on {your sinch number the fax was sent to} |\n| **Body:** | The body will contain data such as number of pages or other relevant metadata of the fax. |\n\nThere will be one PDF attachment with the fax content.\n\n## Configuring your email system for best performance\n\nMake sure you allowlist `sinchfax.com` and `sinch.com` in your spam filter to ensure delivery to your inbox, both on client and server side.\nEnsure your mail server is setup correctly and not on spam lists.\n\n## Encryption\n\nAll emails are sent using TLS during transport from Sinch."
},
{
"name": "Domains",
"description": "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."
},
{
"name": "Templates",
"description": "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."
},
{
"name": "Cover pages",
"description": "You can add cover pages to Sinch Fax either via the API or the [Build dashboard](https://dashboard.sinch.com).\n\nA Fax service can have 0 or more cover pages configured.\n\n### When cover pages are added\n\n#### Via dashboard\n\nIn 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.\n\n**Note:** If you are using Fax to Email, this is currently the only way to add a cover page to your faxes.\n\n#### Via API\n\nWhen sending a fax using the API, you can specify `coverPageId` and supply your own cover page data.\n\n### How to create a cover page\n\nCreate 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.\n\n#### Automatic fields\n\nIf we find the tags described in the table below, we will replace these tokens with fax metadata.\n\n|Tag | Content | Example |Description |\n| ---- | ----- | ----- | ----- |\n|{{from}}| string | +15557897890 | Your Sinch number that you used to send the fax. |\n|{{to}}| string | +15551231234 | The number to which you are sending the fax. |\n|{{date}}| date | 2/4/2025 | The date when the fax was sent. |\n|{{pageCount}}| number | 52 | The total number of pages to be transmitted. |\n\n### Specifying your own dynamic fields in API calls\n\nWhen sending faxes via API you can add any tags you like with `{{}}`` syntax and set those in your app calls for cover page data.\n\nExample:\n If you would like to add the recipient's name and your own message on the cover page:\n\n```json\n/// in your template pdf\nFax to : {{to_name}}\n{{my_custom_message}}\n\n{\n ///other fax fields removed for clarity\n coverPageData: {\n \"to_name\": \"Dr. John Smith\",\n \"my_custom_message\": \"I know you are busy please take on this patient\"\n }\n}\n```"
},
{
"name": "Error Messages",
"description": "## Fax Error Messages\n\nWhen your receive a callback from the fax api notifying you of a failure, it will contain two values\nthat can help you understand what went wrong: an errorCode and an type.\n\nThe type will give you a general idea of why the operation failed, whereas the errorCode describes the issue in more detail. Below we list the error_codes for the API, segmented by their corresponding error_type.\n\n{% partial file=\"/partials/fax/errors/_schemas.md\"/ %}\n\n## General Error Messages\n\nRequest errors are returned as HTTP status codes. The following table lists the possible error codes and their meaning.\n\nThe type will give you a general idea of why the operation failed, whereas the errorCode describes the issue in more detail. Below we list the error_codes for the API, segmented by their corresponding error_type.\n\n## Http Error Codes\n\n### 400 - Bad Request\n\n```json\n{\n \"code\": \"404\",\n \"error\": \"Bad Request\",\n \"message\": \"\n The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.\n It could be invalid JSON, missing required fields, or other issues.\"\n}\n```\n\n### 401 - Unauthorized\n\nEmpty body, or you have the wrong API key, secret, or project.\n\n### 402 - Payment required\n\n```json\n{\n \"code\": \"402\",\n \"error\": \"Payment required\",\n \"message\": \"You have reached 0 balance on your account please make a payment.\"\n}\n```\n\n\n### 404 - Not found\n\n```json\n{\n \"code\": \"404\",\n \"error\": \"Not found\",\n \"message\": \"The resource is not found, not available, or does not exist.\"\n}\n```\n\n### 422 - Unprocessable Content (Invalid parameters)\n\n```json\n{\n \"code\": \"422\",\n \"error\": \"Invalid parameters\",\n \"message\": \"The request could not be understood by the server due to malformed syntax.\n The client SHOULD NOT repeat the request without modifications.\"\n details: {\n fieldViolations: [\n {\n field: \"to\",\n description: \"The (+15551) is not a valid phone number\"\n }\n ]\n\n }\n```\n\n### 429 Rate limit exceeded\n\nRate limit exceeded, please back off and try again later. If you need higher rate please contact support.\n\n\n### 500 - Internal Server Error\n\nProbably no body, but if there is a body it will look like this:\n\n```json\n{\n \"code\": \"500\",\n \"error\": \"Internal service error\",\n \"message\": \"Most likely a temporary issue, please try again later. If the problem persists, please back of on this request and contact support.\"\n}\n```\n\n### 800 - URL Connection Error\n\nThis non-http code will be used when there is an issue connecting to the designated callback URL. The response will look like this:\n\n```json\n{\n \"error\": \"Could not connect to URL: https://123.456.789.00\"\n}\n```\n\n\n## Error object\n\nPlease note that the response code is probably the most important part of the response, but the error object will contain more information about the error.\nNot all errors return this object, and the `details` object is not always present."
},
{
"name": "Services",
"description": "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.\n\nThis 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.\n\n## Dashboard\nYou can manage all your fax services and their settings via the [Dashboard](https://dashboard.sinch.com/fax/services).\n\n## Sending a test fax\n\nTo 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.\n"
}
],
"webhooks": {
"incomingFax": {
"post": {
"security": [
{
"WebhookBasicAuth": []
}
],
"operationId": "incomingFaxEvent",
"tags": [
"Faxes",
"Notifications"
],
"summary": "Incoming fax event",
"description": "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](https://dashboard.sinch.com/fax/services) or using the [service API](https://developers.sinch.com/docs/fax/api-reference/fax/services/createnotificationwebhook).\n\n### Example payloads\n\nMultipart/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**.\n\nApplication/json request payloads are a JSON object with the file encoded as a base64 string as part of the JSON object.",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "The value is always `INCOMING_FAX` for this event.",
"enum": [
"INCOMING_FAX"
],
"default": "INCOMING_FAX"
},
"file": {
"description": "The fax content as a PDF attachment to the body",
"type": "string",
"format": "binary",
"contentMediaType": "application/pdf",
"contentEncoding": "binary"
}
}
},
{
"$ref": "#/components/schemas/GenericEvent"
}
]
},
"encoding": {
"file": {
"contentType": "application/pdf"
},
"fax": {
"contentType": "application/json"
},
"event": {
"contentType": "application/json"
}
},
"example": {
"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}"
}
},
"application/json": {
"schema": {
"type": "object",
"properties": {
"event": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvents"
}
],
"description": "Always `INCOMING_FAX` for this event.",
"enum": [
"INCOMING_FAX"
],
"default": "INCOMING_FAX"
},
"eventTime": {
"description": "Time of the event.",
"type": "string",
"format": "date-time"
},
"fax": {
"description": "The incoming fax.",
"$ref": "#/components/schemas/Fax"
},
"file": {
"description": "The base64 encoded file.",
"type": "string",
"example": "{base64_encodedData}"
},
"fileType": {
"description": "The file type of the attached file.",
"type": "string",
"example": "PDF"
}
}
},
"example": {
"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": "{base64_encodedData}",
"fileType": "PDF"
}
}
}
},
"responses": {
"200": {
"description": "Returns a 200 OK response if the webhook was received successfully."
}
}
}
},
"faxCompleted": {
"post": {
"security": [
{
"WebhookBasicAuth": []
}
],
"summary": "Fax completed",
"description": "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.",
"operationId": "faxCompletedCallback",
"tags": [
"Notifications",
"Faxes"
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "Always fax completed for this event.",
"enum": [
"FAX_COMPLETED"
],
"default": "FAX_COMPLETED"
},
"file": {
"description": "The fax content as pdf attachment to the body",
"type": "string",
"format": "binary",
"contentMediaType": "application/pdf",
"contentEncoding": "binary"
}
}
},
{
"$ref": "#/components/schemas/GenericEvent"
}
]
},
"encoding": {
"file": {
"contentType": "application/pdf"
},
"fax": {
"contentType": "application/json"
},
"event": {
"contentType": "application/json"
}
},
"example": {
"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}"
}
},
"application/json": {
"schema": {
"type": "object",
"properties": {
"event": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvents"
}
],
"description": "Always `FAX_COMPLETED` for this event.",
"enum": [
"FAX_COMPLETED"
],
"default": "FAX_COMPLETED"
},
"eventTime": {
"description": "Time of the event.",
"type": "string",
"format": "date-time"
},
"fax": {
"description": "The incoming fax.",
"$ref": "#/components/schemas/Fax"
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FaxBase64File"
}
}
}
},
"example": {
"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": "application/json",
"projectId": "YOUR_PROJECT_ID",
"serviceId": "YOUR_SERVICE_ID"
},
"files": [
{
"file": "{base64ecnodeddata}",
"fileType": "PDF"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Returns a 200 OK response if the webhook was received successfully."
}
}
}
}
},
"paths": {
"/faxes": {
"post": {
"tags": [
"Faxes"
],
"summary": "Send a fax",
"description": "Create and send a fax.\n\nFax content may be supplied via one or more files or URLs of supported filetypes.\n\nThis endpoint supports the following content types for the fax payload:\n\n - Multipart/form-data\n - Application/json\n\nWe 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\nwith the content of the fax as an attachment to the body, *unless* you specify callbackUrlContentType as application/json.\n\n#### file(s)\nFiles may be included in the POST request as multipart/form-data parts.\n\n#### contentUrl\nAny 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.\n\nPlease 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.",
"operationId": "sendFax",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"required": [
"to"
],
"allOf": [
{
"type": "object",
"properties": {
"to": {
"description": "When you send a fax you can specify a single number or a list of numbers separated by ;.\nPlease 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.\n\nWhen you receive a fax, this is the number where the fax is sent to.",
"$ref": "#/components/schemas/PhoneNumber"
},
"file": {
"description": "The file(s) you want to send as a fax as body attachment.",
"type": "string",
"format": "binary"
}
}
},
{
"$ref": "#/components/schemas/Fax"
}
]
},
"encoding": {
"files": {
"contentType": "application/octet-stream"
}
},
"examples": {
"SendFax": {
"$ref": "#/components/examples/SendWebPageAsFax"
},
"SendFileAsFaxWithCoverPage": {
"$ref": "#/components/examples/SendFileAsFaxWithCoverPage"
},
"SendFileAsFax": {
"$ref": "#/components/examples/SendFileAsFax"
}
}
},
"application/json": {
"schema": {
"required": [
"to"
],
"allOf": [
{
"type": "object",
"properties": {
"to": {
"description": "When you send a fax you can specify a single number or a list of numbers separated by ;.\nPlease 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.\n\nWhen you receive a fax, this is the number where the fax is sent to.",
"$ref": "#/components/schemas/PhoneNumber"
},
"from": {
"$ref": "#/components/schemas/PhoneNumber",
"description": "The number you want to send a fax from. This number must be associated with your account.\nIf you do not specify a from number, we will use the first number associated with your account."
}
}
},
{
"$ref": "#/components/schemas/FaxBase64Array"
},
{
"$ref": "#/components/schemas/Fax"
}
]
},
"examples": {
"SendFileAsFaxWithCoverPage": {
"$ref": "#/components/examples/SendFileAsFaxWithCoverPage"
},
"SendWebPageAsFax": {
"$ref": "#/components/examples/SendWebPageAsFax"
},
"SendFileAsFaxJson": {
"$ref": "#/components/examples/SendFileAsFaxJson"
}
}
}
}
},
"responses": {
"200": {
"description": "The created fax",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Fax"
},
"example": {
"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"
}
}
}
}
}
},
"get": {
"tags": [
"Faxes"
],
"summary": "List faxes",
"operationId": "getFaxes",
"description": "List faxes sent (OUTBOUND) or received (INBOUND), set parameters to filter the list.\nExample: Return calls made between 1st of January 2021 and 10th of January 2021.\n```\n created>=2021-01-01&startTime<=2021-01-10\n```",
"parameters": [
{
"name": "serviceId",
"in": "query",
"description": "Limits results to faxes that were sent using the specified service.",
"schema": {
"type": "string",
"example": "YOUR_SERVICE_ID"
}
},
{
"name": "createTime",
"in": "query",
"description": "Filter calls based on `createTime`. If you make the query more precise, fewer results will be returned.\nFor 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.\nThis 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.\nIt is also possible to submit partial dates. For example, `createTime=2021-02` will return all calls for February 2021.\n\nIf not value is submitted, the default value is the prior week.",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "direction",
"in": "query",
"description": "Limits results to faxes with the specified direction.",
"schema": {
"$ref": "#/components/schemas/FaxDirection"
},
"example": "OUTBOUND"
},
{
"name": "status",
"in": "query",
"description": "Limits results to faxes with the specified status.",
"schema": {
"$ref": "#/components/schemas/FaxStatus"
},
"example": "COMPLETED"
},
{
"name": "to",
"in": "query",
"description": "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.",
"schema": {
"$ref": "#/components/schemas/PhoneNumber"
},
"example": "+14155552222"
},
{
"name": "from",
"in": "query",
"description": "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.",
"schema": {
"$ref": "#/components/schemas/PhoneNumber"
}
},
{
"$ref": "#/components/parameters/Labels"
},
{
"$ref": "#/components/parameters/Format"
},
{
"$ref": "#/components/parameters/PageSize"
},
{
"$ref": "#/components/parameters/Page"
}
],
"responses": {
"200": {
"description": "Result of the query.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListFaxesObject"
}
}
}
}
}
}
},
"/faxes/{id}": {
"get": {
"tags": [
"Faxes"
],
"summary": "Get fax",
"description": "Get fax information using the ID number of the fax.",
"operationId": "getFaxInfoPerId",
"parameters": [
{
"$ref": "#/components/parameters/Id"
}
],
"responses": {
"200": {
"description": "The fax",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Fax"
},
"example": {
"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
}
}
}
}
}
}
},
"/faxes/{id}/file": {
"get": {
"tags": [
"Faxes"
],
"summary": "Download fax content",
"description": "Download the fax content.",
"operationId": "getFaxFilebyId",
"parameters": [
{
"$ref": "#/components/parameters/Id"
}
],
"responses": {
"200": {
"description": "A file for the fax you requested will be returned in the format you specified.",
"content": {
"application/pdf": {
"schema": {
"description": "A PDF file named 'fax-1234.pdf' containing all files sent for fax #1234.",
"type": "string",
"format": "binary"
}
}
}
}
}
},
"delete": {
"tags": [
"Faxes"
],
"summary": "Delete fax content",
"description": "Delete the fax content for a fax using the ID number of the fax.\nPlease note that this only deletes the content of the fax from storage.",
"operationId": "deleteFaxContentById",
"parameters": [
{
"$ref": "#/components/parameters/Id"
}
],
"responses": {
"204": {
"description": "The fax content was deleted."
}
}
}
},
"/faxes/{id}/file.{fileFormat}": {
"get": {
"tags": [
"Faxes"
],
"summary": "Download fax content",
"description": "Download the fax content.",
"operationId": "getFaxFileByIdDeprecated",
"deprecated": true,
"parameters": [
{
"$ref": "#/components/parameters/Id"
},
{
"name": "fileFormat",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"pdf"
],
"default": "pdf",
"x-enumDescriptions": {
"pdf": "PDF format"
}
},
"description": "The file format to download. Currently only PDF is supported.",
"example": "pdf"
}
],
"responses": {
"200": {
"description": "A file for the fax you requested will be returned in the format you specified.",
"content": {
"application/pdf": {
"schema": {
"description": "A PDF file named 'fax-1234.pdf' containing all files sent for fax #1234.",
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/services": {
"post": {
"description": "Creates a new service that you can use to set default configuration values.",
"operationId": "createService",
"summary": "Create a service",
"tags": [
"Services"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Service"
}
}
}
},
"responses": {
"201": {
"description": "The newly created service",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Service"
}
}
}
}
}
},
"get": {
"description": "Get a list of services for a project.",
"summary": "List services",
"operationId": "listServices",
"tags": [
"Services"
],
"parameters": [
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"default": 20,
"example": 20,
"maximum": 1000
},
"description": "Number of services to return on each request."
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
},
"description": "Optional. The page to fetch. If not specified, the first page will be returned."
}
],
"responses": {
"200": {
"$ref": "#/components/responses/ServiceList"
}
}
}
},
"/services/{id}": {
"get": {
"description": "Get a service resource.",
"summary": "Get a service",
"operationId": "getService",
"tags": [
"Services"
],
"parameters": [
{
"name": "id",
"description": "The service ID you want to update.",
"required": true,
"schema": {
"type": "string"
},
"in": "path"
}
],
"responses": {
"200": {
"description": "The requested service, or an [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Service"
}
}
}
}
}
},
"patch": {
"description": "Update settings on the service.",
"summary": "Update a Service",
"operationId": "updateService",
"parameters": [
{
"name": "id",
"required": true,
"description": "The service ID you want to update.",
"schema": {
"type": "string"
},
"in": "path"
}
],
"tags": [
"Services"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Service"
}
}
}
},
"responses": {
"200": {
"description": "The updated service, or an [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Service"
}
}
}
}
}
},
"delete": {
"description": "Removes a service from your project.",
"operationId": "removeService",
"summary": "Remove a service",
"tags": [
"Services"
],
"parameters": [
{
"name": "id",
"description": "The serviceId you want to remove from your project.",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "The service removed from the project, or an [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)"
}
}
}
},
"/services/{id}/coverPages": {
"parameters": [
{
"name": "id",
"description": "the serviceId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"post": {
"description": "Add a cover page to your service",
"summary": "Add cover page",
"operationId": "addCoverPage",
"tags": [
"Cover pages"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoverPage"
}
}
}
},
"responses": {
"200": {
"description": "The added coverpage, or an [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoverPage"
}
}
}
}
}
},
"get": {
"description": "List all cover page to a service",
"summary": "List cover pages",
"operationId": "listCoverPages",
"tags": [
"Cover pages"
],
"responses": {
"200": {
"description": "List of coverpages [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"coverPages": {
"description": "List of cover pages",
"type": "array",
"items": {
"$ref": "#/components/schemas/CoverPage"
}
}
}
},
{
"$ref": "#/components/schemas/Pagination"
}
]
}
}
}
}
}
}
},
"/services/{id}/coverPages/{coverPageId}": {
"parameters": [
{
"name": "id",
"description": "The serviceId containing the cover page you want to work with.",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "coverPageId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "The coverPageId you want to work with."
}
}
],
"delete": {
"tags": [
"Cover pages"
],
"operationId": "deleteCoverPage",
"summary": "Delete a cover page",
"description": "Remove delete a cover page from a service.",
"responses": {
"204": {
"description": "The cover page was deleted."
}
}
},
"get": {
"tags": [
"Cover pages"
],
"operationId": "getCoverPage",
"summary": "Get a cover page",
"description": "Get a cover page by ID.",
"responses": {
"200": {
"description": "The requested cover page, or an [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoverPage"
}
}
}
}
}
}
},
"/services/{id}/numbers": {
"get": {
"description": "List numbers for a service.",
"summary": "List numbers for service",
"operationId": "listNumbersForService",
"tags": [
"Services"
],
"parameters": [
{
"name": "id",
"required": true,
"description": "The serviceId containing the numbers you want to list.",
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"default": 20,
"example": 20,
"maximum": 1000
},
"description": "Number of items to return on each page."
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
},
"description": "Optional. The page to fetch. If not specified, the first page will be returned."
}
],
"responses": {
"200": {
"description": "The list of numbers, or an [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"numbers": {
"description": "List of phone numbers",
"type": "array",
"items": {
"$ref": "#/components/schemas/ServicePhoneNumber"
}
}
}
},
{
"$ref": "#/components/schemas/Pagination"
}
]
}
}
}
}
}
}
},
"/services/{id}/numbers/{phoneNumber}/emails": {
"parameters": [
{
"name": "phoneNumber",
"description": "The phone number you want to get emails for.",
"required": true,
"in": "path",
"schema": {
"type": "string",
"description": "A phone number in e.164 format.",
"example": "+15612600684"
}
},
{
"name": "id",
"description": "The serviceId containing the numbers you want to list.",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"get": {
"summary": "List emails for a number",
"description": "List any emails for a number.",
"operationId": "getEmailsForNumber",
"tags": [
"Fax to Email"
],
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to fetch. If not specified, the first page will be returned.",
"schema": {
"type": "integer",
"default": 1,
"example": 1
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"default": 100,
"example": 20,
"maximum": 1000
},
"description": "Number of items to return on each page."
}
],
"responses": {
"200": {
"description": "A list of emails associated with the number.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"emails": {
"description": "List of emails numbers",
"type": "array",
"items": {
"type": "string",
"format": "email"
}
}
}
},
{
"$ref": "#/components/schemas/Pagination"
}
]
}
}
}
}
}
}
},
"/services/{serviceId}/emails": {
"get": {
"description": "List emails for the project.",
"summary": "List emails",
"operationId": "getEmailsForProject",
"tags": [
"Fax to Email"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId containing the emails you want to list.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to fetch. If not specified, the first page will be returned.",
"schema": {
"type": "integer",
"default": 1,
"example": 1
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"default": 100,
"example": 20,
"maximum": 1000
},
"description": "Number of items to return on each page."
}
],
"responses": {
"200": {
"description": "A list of emails associated with the project.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"emails": {
"description": "List of emails",
"type": "array",
"items": {
"$ref": "#/components/schemas/Email"
}
}
}
},
{
"$ref": "#/components/schemas/Pagination"
}
]
}
}
}
}
}
},
"post": {
"description": "Add an email to the specified service to be used for sending and receiving faxes. Default settings for permissions parameter is `both`.",
"summary": "Add an email",
"operationId": "createEmailForProject",
"tags": [
"Fax to Email"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId to which you want to add the email.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Email"
},
"example": {
"email": "user@domain.com",
"phoneNumbers": [
{
"number": "+14155552222",
"permissions": "both"
}
]
}
}
}
},
"responses": {
"201": {
"description": "The added email",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Email"
}
}
}
}
}
}
},
"/services/{serviceId}/emails/{email}": {
"parameters": [
{
"name": "serviceId",
"description": "The serviceId containing the email you want to work with.",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "email",
"description": "The email you want to work with.",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"put": {
"description": "Set the numbers for an email.",
"operationId": "updateEmail",
"summary": "Update numbers for email",
"tags": [
"Fax to Email"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"phoneNumbers"
],
"properties": {
"phoneNumbers": {
"description": "List of numbers",
"type": "array",
"items": {
"$ref": "#/components/schemas/Number"
}
}
}
},
"example": {
"phoneNumbers": [
{
"number": "+14155552222",
"permissions": "both"
}
]
}
}
}
},
"responses": {
"200": {
"description": "The added email",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Email"
}
}
}
}
}
},
"delete": {
"tags": [
"Fax to Email"
],
"summary": "Remove email",
"description": "Delete an email and associated numbers to that email to disable that email from sending and receiving faxes.",
"operationId": "deleteEmail",
"responses": {
"204": {
"description": "No content: **The email was deleted**"
}
}
}
},
"/services/{serviceId}/emails/{email}/numbers": {
"parameters": [
{
"name": "serviceId",
"description": "The serviceId containing the email you want to work with.",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "email",
"description": "The email you want to get numbers for.",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"default": 20,
"example": 20,
"maximum": 1000
},
"description": "Number of items to return on each page."
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
},
"description": "Optional. The page to fetch. If not specified, the first page will be returned."
}
],
"get": {
"description": "Get configured numbers for an email",
"summary": "Get numbers for email",
"operationId": "getNumbersByEmail",
"tags": [
"Fax to Email"
],
"responses": {
"200": {
"description": "A list of numbers associated with the email",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"phoneNumbers": {
"description": "List of numbers",
"type": "array",
"items": {
"$ref": "#/components/schemas/ServicePhoneNumber"
}
}
}
},
{
"$ref": "#/components/schemas/Pagination"
}
]
}
}
}
}
}
}
},
"/services/{serviceId}/domains": {
"get": {
"tags": [
"Domains"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId containing the domains you want to list.",
"required": true,
"schema": {
"type": "string",
"example": "01GVRB50KEQFFE1SGMPFRNBG6J"
}
}
],
"summary": "List domains",
"description": "List existing domains for the specified service.",
"operationId": "listDomains",
"responses": {
"200": {
"description": "The domains contained in the service.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DomainsListResponse"
}
}
}
}
}
}
},
"/services/{serviceId}/domains/{domainName}": {
"post": {
"tags": [
"Domains"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId where you want to create a domain.",
"required": true,
"schema": {
"type": "string",
"example": "01GVRB50KEQFFE1SGMPFRNBG6J"
}
},
{
"name": "domainName",
"in": "path",
"description": "The name of the domain to create.",
"required": true,
"schema": {
"type": "string",
"example": "yourdomain.com"
}
}
],
"summary": "Create a domain",
"description": "Creates a new domain on the specified service to host email templates.",
"operationId": "createDomain",
"responses": {
"201": {
"description": "The created domain.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDomainResponse"
}
}
}
}
}
},
"get": {
"tags": [
"Domains"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId containing the domain you want to retrieve.",
"required": true,
"schema": {
"type": "string",
"example": "01GVRB50KEQFFE1SGMPFRNBG6J"
}
},
{
"name": "domainName",
"in": "path",
"description": "The name of the domain you want to retrieve.",
"required": true,
"schema": {
"type": "string",
"example": "yourdomain.com"
}
}
],
"summary": "Get domain",
"description": "Retrieve a specific domain for the specified service.",
"operationId": "getDomain",
"responses": {
"200": {
"description": "The details of the domain.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DomainDetailsResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"Domains"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId containing the domain you want to delete.",
"required": true,
"schema": {
"type": "string",
"example": "01GVRB50KEQFFE1SGMPFRNBG6J"
}
},
{
"name": "domainName",
"in": "path",
"description": "The name of the domain you want to delete.",
"required": true,
"schema": {
"type": "string",
"example": "yourdomain.com"
}
}
],
"summary": "Delete domain",
"description": "Delete a specific domain for the specified service.",
"operationId": "deleteDomain",
"responses": {
"204": {
"description": "No content"
}
}
}
},
"/services/{serviceId}/domains/{domainName}:verify": {
"get": {
"tags": [
"Domains"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId containing the domain you want to verify.",
"required": true,
"schema": {
"type": "string",
"example": "01GVRB50KEQFFE1SGMPFRNBG6J"
}
},
{
"name": "domainName",
"in": "path",
"description": "The name of the domain you want to verify.",
"required": true,
"schema": {
"type": "string",
"example": "yourdomain.com"
}
}
],
"summary": "Verify domain",
"description": "Verify a specific domain for the specified service.",
"operationId": "verifyDomain",
"responses": {
"200": {
"description": "The verification status of the domain.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyDomainResponse"
}
}
}
}
}
}
},
"/services/{serviceId}/domains/{domainName}/templates": {
"get": {
"tags": [
"Templates"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId containing the templates you want to list.",
"required": true,
"schema": {
"type": "string",
"example": "01GVRB50KEQFFE1SGMPFRNBG6J"
}
},
{
"name": "domainName",
"in": "path",
"description": "The name of the domain containing the templates you want to list.",
"required": true,
"schema": {
"type": "string",
"example": "yourdomain.com"
}
}
],
"summary": "List templates for domain",
"description": "List templates for a specific domain for the specified service.",
"operationId": "listTemplates",
"responses": {
"200": {
"description": "The returned templates.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplatesDomainNameResponse"
}
}
}
}
}
}
},
"/services/{serviceId}/domains/{domainName}/templates/{templateName}": {
"get": {
"tags": [
"Templates"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId containing the templates you want to list.",
"required": true,
"schema": {
"type": "string",
"example": "01GVRB50KEQFFE1SGMPFRNBG6J"
}
},
{
"name": "domainName",
"in": "path",
"description": "The name of the domain containing the template you want to get.",
"required": true,
"schema": {
"type": "string",
"example": "yourdomain.com"
}
},
{
"name": "templateName",
"in": "path",
"description": "The name of the template you want to get.",
"required": true,
"schema": {
"$ref": "#/components/schemas/TemplateName"
}
}
],
"summary": "Get template",
"description": "Retrieve a named template for a specific domain for the specified service.",
"operationId": "getTemplate",
"responses": {
"200": {
"description": "The returned template.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplateByNameResponse"
}
}
}
}
}
},
"put": {
"tags": [
"Templates"
],
"parameters": [
{
"name": "serviceId",
"in": "path",
"description": "The serviceId containing the templates you want to update.",
"required": true,
"schema": {
"type": "string",
"example": "01GVRB50KEQFFE1SGMPFRNBG6J"
}
},
{
"name": "domainName",
"in": "path",
"description": "The name of the domain containing the templates you want to update.",
"required": true,
"schema": {
"type": "string",
"example": "yourdomain.com"
}
},
{
"name": "templateName",
"in": "path",
"description": "The name of the template you want to update.",
"required": true,
"schema": {
"$ref": "#/components/schemas/TemplateName"
}
}
],
"summary": "Update template",
"description": "Update a template for a specific domain for the specified service.",
"operationId": "updateTemplate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTemplateRequest"
},
"examples": {
"successfulOutboundFax": {
"summary": "successful outbound fax",
"value": {
"template": "
A fax sent to you from: {{from}} was not received successfully.
Fax Id:
{{id}}
From:
{{from}}
To:
{{to}}
Number of pages:
{{numberOfPages}}
Number of retries:
{{retryCount}}
Price:
{{currencyCode}} {{amount}}
Thanks!
"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The updated template.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplateByNameResponse"
}
}
}
}
}
}
}
},
"components": {
"examples": {
"SendWebPageAsFax": {
"summary": "Send a web page as a fax",
"value": {
"to": "+14155552222",
"contentUrl": "https://developers.sinch.com/fax/fax.pdf"
}
},
"SendFileAsFax": {
"summary": "Send a file as a fax",
"value": {
"to": "+14155552222",
"file": "//path/to/file.pdf"
}
},
"SendFileAsFaxWithCoverPage": {
"summary": "Send a fax with cover page",
"value": {
"to": "+14155552222",
"file": "//path/to/file.pdf",
"coverPageId": "12312kj312kl3j12k3j",
"coverPageData": {
"message": "To Dr. Smith regarding referral"
}
}
},
"SendFileAsFaxJson": {
"summary": "Send a file as a fax",
"value": {
"to": "+14155552222",
"files": [
{
"file": "{base64EncodedData}",
"fileType": "PDF"
}
]
}
}
},
"responses": {
"ServiceList": {
"description": "List of services, or an [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"services": {
"description": "List of services.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Service"
}
}
}
},
{
"$ref": "#/components/schemas/Pagination"
}
]
}
}
}
}
},
"schemas": {
"Number": {
"description": "A phone number and its permissions.",
"type": "object",
"properties": {
"faxNumber": {
"$ref": "#/components/schemas/PhoneNumber"
},
"permissions": {
"type": "string",
"description": "Allows you to set permissions for sending and receiving faxes to this email/phone number combination. Default value is `both`.",
"x-enumDescriptions": {
"both": "Allows the email to send and receive faxes to this email/phone number combination.",
"send": "Allows the email to only send faxes to this email/phone number combination.",
"receive": "Allows the email to only receive faxes from this email/phone number combination."
},
"enum": [
"both",
"send",
"receive"
],
"default": "both"
}
}
},
"Email": {
"type": "object",
"required": [
"email",
"phoneNumbers"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"example": "user@domain.com"
},
"phoneNumbers": {
"description": "Numbers you want to associate with this email.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Number"
}
},
"projectId": {
"readOnly": true,
"x-version": 1,
"allOf": [
{
"$ref": "#/components/schemas/ProjectId"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The date and time the email configuration was created."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The date and time the email configuration was last updated."
}
}
},
"TemplateName": {
"type": "string",
"description": "The name of the email template.",
"enum": [
"successful outbound fax",
"unsuccessful outbound fax",
"successful inbound fax",
"unsuccessful inbound fax"
],
"x-enumDescriptions": {
"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"
},
"FaxDirection": {
"type": "string",
"description": "The direction of the fax.",
"readOnly": true,
"enum": [
"OUTBOUND",
"INBOUND"
],
"x-enumDescriptions": {
"OUTBOUND": "The fax was sent by you via the API.",
"INBOUND": "The fax was received on one of your numbers."
},
"example": "OUTBOUND"
},
"Fax": {
"type": "object",
"properties": {
"id": {
"readOnly": true,
"allOf": [
{
"$ref": "#/components/schemas/FaxId"
}
]
},
"direction": {
"allOf": [
{
"$ref": "#/components/schemas/FaxDirection"
}
],
"readOnly": true
},
"from": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"readOnly": false,
"description": "For `INBOUND` faxes, this is the number where the fax is sent from\nFor `OUTBOUND` faxes, this is the Sinch number you want to have as sender"
},
"to": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"readOnly": false,
"description": "For `INBOUND` faxes, this is the Sinch number someone sent the fax to.\nFor `OUTBOUND` faxes, this is the phone number you want to send a fax to.\n\nYou can add multiple numbers by adding them as an array. For example:\n\n application/json\n\n ```json\n \"to\": [\"+14155552222\", \"+14155553333\"]\n ```\n\n multipart/form\n ```json\n to=+14155552222&to=+14155553333\n\n ```"
},
"contentUrl": {
"anyOf": [
{
"type": "string",
"format": "url",
"description": "Single URL",
"example": "https://example.com/fax.pdf"
},
{
"type": "array",
"items": {
"type": "string"
},
"description": "Multiple URLs",
"example": [
"www.google.com",
"www.sinch.com"
]
}
],
"writeOnly": true,
"format": "URL",
"description": "Give us any URL on the Internet (including ones with basic authentication)\nAt least one file or contentUrl parameter is required.\nPlease 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.\nIf the file parameter is specified as well, content from URLs will be rendered before content from files.\n\nYou can add multiple URLs by adding them as an array them with a comma when posting as multipart/form-data\n\nFor 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/\"]`",
"example": "https://developers.sinch.com/fax/fax.pdf"
},
"numberOfPages": {
"type": "integer",
"readOnly": true,
"description": "The number of pages in the fax."
},
"status": {
"$ref": "#/components/schemas/FaxStatus"
},
"price": {
"description": "The total price for this fax. This field is populated after the final fax price is calculated.",
"allOf": [
{
"$ref": "#/components/schemas/Money"
}
],
"readOnly": true
},
"barCodes": {
"description": "The bar codes found in the fax. This field is populated when Sinch detects bar codes on incoming faxes.",
"readOnly": true,
"type": "array",
"items": {
"$ref": "#/components/schemas/BarCode"
}
},
"createTime": {
"readOnly": true,
"type": "string",
"format": "date-time",
"description": "A timestamp representing the time when the initial API call was made."
},
"completedTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "If the job is complete, this is a timestamp representing the time the job was completed."
},
"pagesSentSuccessfully": {
"type": "integer",
"description": "The number of pages successfully sent to the receiving side in the fax.",
"readOnly": true,
"example": 3
},
"headerText": {
"description": "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.",
"type": "string",
"maximum": 50,
"default": ""
},
"headerPageNumbers": {
"type": "boolean",
"description": "If true, page numbers will be displayed in the header. Default is true.",
"default": true
},
"headerTimeZone": {
"type": "string",
"format": "timezone",
"description": "A [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string specifying the timezone for the header timestamp.",
"default": "America/New_York"
},
"retryDelaySeconds": {
"description": "The number of seconds to wait between retries if the fax is not yet completed.",
"type": "integer",
"minimum": 30,
"maximum": 300,
"default": 60
},
"labels": {
"x-version": 2,
"description": "You can use this to attach labels to your call that you can use in your BI solutions.",
"allOf": [
{
"$ref": "#/components/schemas/Labels"
}
],
"example": {
"customerId": "1234",
"customerName": "John Doe"
}
},
"callbackUrl": {
"type": "string",
"description": "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.\n\nNote: 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.",
"format": "URL",
"example": "https://www.my-website.com/callback"
},
"callbackUrlContentType": {
"description": "The content type of the callback.",
"type": "string",
"default": "multipart/form-data",
"enum": [
"multipart/form-data",
"application/json"
],
"x-enumDescriptions": {
"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": {
"$ref": "#/components/schemas/ImageConversionMethod"
},
"errorType": {
"readOnly": true,
"allOf": [
{
"$ref": "#/components/schemas/ErrorType"
}
]
},
"errorCode": {
"readOnly": true,
"type": "integer",
"description": "One of the error numbers listed in the [Fax Error Messages section](https://developers.sinch.com/docs/fax/api-reference/fax/error-messages)."
},
"errorMessage": {
"readOnly": true,
"type": "string",
"description": "One of the error codes listed in the [Fax Error Messages section](https://developers.sinch.com/docs/fax/api-reference/fax/error-messages)."
},
"maxRetries": {
"readOnly": false,
"type": "integer",
"description": "| The number of times the fax will be retired before cancel. Default value is set in your fax service.\n| The maximum number of retries is 5.",
"maximum": 5,
"minimum": 0
},
"retryCount": {
"readOnly": true,
"type": "integer",
"description": "The number of times the fax has been retried."
},
"hasFile": {
"readOnly": true,
"type": "string",
"description": "Only shown on the fax result. This indicates if the content of the fax is stored with Sinch. (true or false)"
},
"resolution": {
"$ref": "#/components/schemas/Resolution"
},
"coverPageId": {
"type": "string",
"description": "The cover page id you want to use for the fax"
},
"coverPageData": {
"$ref": "#/components/schemas/CoverPageData"
},
"inProgressNotifications": {
"type": "boolean",
"description": "If set to `true`, you will receive a webhook notification for each page sent on an outbound fax.",
"default": false
},
"projectId": {
"readOnly": true,
"x-version": 1,
"allOf": [
{
"$ref": "#/components/schemas/ProjectId"
}
]
},
"serviceId": {
"readOnly": false,
"x-version": 1,
"allOf": [
{
"$ref": "#/components/schemas/ServiceId"
}
]
}
}
},
"FaxBase64Array": {
"description": "An array of base64 encoded files",
"type": "object",
"properties": {
"files": {
"type": "array",
"description": "An array of base64 encoded files",
"items": {
"$ref": "#/components/schemas/FaxBase64File"
}
}
}
},
"FaxBase64File": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "base64",
"contentEncoding": "base64",
"description": "When application/json Base64 encoded file content, this is only present when using application/json for request/response.",
"example": "{base64-encoded content}"
},
"fileType": {
"type": "string",
"description": "When request/response is application json and file is part of payload. This is the file type of the file.",
"enum": [
"DOCX",
"PDF",
"TIF",
"JPG",
"TXT",
"HTML",
"PNG"
],
"x-enumDescriptions": {
"DOCX": "Microsoft Word",
"PDF": "PDF",
"TIF": "TIFF",
"JPG": "JPEG",
"TXT": "Text",
"HTML": "HTML",
"PNG": "PNG"
}
}
}
},
"BarCode": {
"type": "object",
"description": "Sinch will scan all pages of all incoming faxes for Code-128 and DataMatrix bar codes and include this information in webhook requests and via the API.",
"properties": {
"type": {
"type": "string",
"description": "The type of barcode found.",
"enum": [
"CODE_128",
"DATA_MATRIX"
],
"x-enumDescriptions": {
"CODE_128": "Code-128 barcode.",
"DATA_MATRIX": "DataMatrix barcode."
}
},
"page": {
"description": "The page number on which the barcode was found.",
"type": "integer"
},
"value": {
"description": "The information of the barcode.",
"type": "string"
}
}
},
"ListFaxesObject": {
"type": "object",
"allOf": [
{
"type": "object",
"description": "A list of faxes with pagination information.",
"properties": {
"faxes": {
"type": "array",
"description": "An array of faxes",
"items": {
"$ref": "#/components/schemas/Fax"
}
}
}
},
{
"$ref": "#/components/schemas/Pagination"
}
]
},
"CoverPage": {
"description": "A cover page resource",
"type": "object",
"required": [
"file",
"name"
],
"properties": {
"id": {
"type": "string",
"format": "ulid",
"readOnly": true,
"description": "ID of the cover page"
},
"name": {
"description": "The friendly name of the cover page.",
"example": "Acme Company cover page"
},
"file": {
"type": "object",
"required": [
"fileContent",
"fileType"
],
"properties": {
"fileContent": {
"type": "string",
"format": "base64",
"contentEncoding": "base64",
"description": "A PDF Cover encoded as base64"
},
"fileType": {
"type": "string",
"enum": [
"PDF"
],
"description": "For now only PDF is supported.",
"x-enumDescriptions": {
"PDF": "A PDF file."
},
"default": "PDF"
}
},
"description": "A PDF Cover encoded as base64"
},
"projectId": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectId"
}
],
"readOnly": true
},
"serviceId": {
"allOf": [
{
"$ref": "#/components/schemas/ServiceId"
}
],
"readOnly": true
},
"createdTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The date and time the cover page was created."
},
"updatedTime": {
"type": "string",
"readOnly": true,
"format": "date-time",
"description": "The date and time the cover page was updated."
}
}
},
"Service": {
"type": "object",
"description": "You can use the default created service, or create multiple services within the same project to have different default behavior for all your different faxing use cases.",
"properties": {
"id": {
"$ref": "#/components/schemas/ServiceId"
},
"name": {
"type": "string",
"description": "A friendly name for the service. Maximum is 60 characters.",
"example": "Default service",
"default": "Default service"
},
"incomingWebhookUrl": {
"type": "string",
"x-version": 1,
"description": "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.\n\nNote: If a webhook uses basicauth credentials, when the webhook URL is retrieved those credentials are masked. It is not possible to retrieve previously-set credentials through the API. ",
"readOnly": false,
"example": "https://yourserver/incomingFax"
},
"webhookContentType": {
"description": "The content type of the webhook.",
"type": "string",
"default": "multipart/form-data",
"enum": [
"multipart/form-data",
"application/json"
],
"x-enumDescriptions": {
"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."
}
},
"defaultForProject": {
"x-version": 1,
"type": "boolean",
"format": "string",
"description": "If set to true this is the service used to create faxes when no serviceId is specified in the API endpoints.",
"default": false,
"x-internal": "When an account and project is created, a default service for Voice should be created, and the test number should be assigned to this service"
},
"defaultFrom": {
"x-version": 1,
"type": "string",
"description": "One of your Sinch numbers connected to this service or any of your verified numbers."
},
"numberOfRetries": {
"type": "integer",
"description": "The number of times to retry sending a fax if it fails. Default is 3. Maximum is 5.",
"default": 3
},
"retryDelaySeconds": {
"description": "The number of seconds to wait between retries if the fax is not yet completed.",
"type": "integer",
"minimum": 30,
"maximum": 300,
"default": 60
},
"imageConversionMethod": {
"$ref": "#/components/schemas/ImageConversionMethod"
},
"coverPageId": {
"type": "string",
"format": "ulid",
"description": "If a value it will always add that cover page id to outbound faxes",
"x-internal": "in ui this will be a select list of the pages on the service"
},
"saveOutboundFaxDocuments": {
"description": "Save fax documents with Sinch when you send faxes",
"type": "boolean",
"default": true
},
"saveInboundFaxDocuments": {
"description": "Save fax documents with Sinch when you receive faxes",
"type": "boolean",
"default": true
},
"scanIncomingBarcodes": {
"type": "boolean",
"description": "If set to true, barcodes will be detected on incoming faxes.",
"default": false
},
"inProgressNotifications": {
"type": "boolean",
"description": "If set to `true`, you will receive a webhook notification for each page sent on an outbound fax.",
"default": false
},
"projectId": {
"$ref": "#/components/schemas/ProjectId",
"readOnly": true
},
"resolution": {
"$ref": "#/components/schemas/Resolution"
},
"createdAt": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The date and time the service was created."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The date and time the service was last updated."
}
}
},
"ImageConversionMethod": {
"type": "string",
"description": "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"
],
"x-enumDescriptions": {
"HALFTONE": "Converts the image to halftone.",
"MONOCHROME": "Converts the image to monochrome."
},
"default": "HALFTONE"
},
"ServicePhoneNumber": {
"type": "object",
"properties": {
"phoneNumber": {
"$ref": "#/components/schemas/PhoneNumber"
},
"permissions": {
"type": "string",
"description": "Allows you to set permissions for sending and receiving faxes to this email/phone number combination. Default value is `both`.",
"x-enumDescriptions": {
"both": "Allows the email to send and receive faxes to this email/phone number combination.",
"send": "Allows the email to only send faxes to this email/phone number combination.",
"receive": "Allows the email to only receive faxes from this email/phone number combination."
},
"enum": [
"both",
"send",
"receive"
],
"default": "both"
},
"projectId": {
"$ref": "#/components/schemas/ProjectId",
"readOnly": true
},
"serviceId": {
"$ref": "#/components/schemas/ServiceId",
"readOnly": true
}
}
},
"FaxId": {
"type": "string",
"readOnly": true,
"description": "The id of a fax",
"example": "01F3J0G1M4WQR6HGY6HCF6JA0K"
},
"WebhookEvents": {
"type": "string",
"enum": [
"INCOMING_FAX",
"FAX_COMPLETED"
],
"x-enumDescriptions": {
"INCOMING_FAX": "A webhook event triggered by an fax is incoming.",
"FAX_COMPLETED": "A webhook event triggered by a fax that has successfully completed."
},
"description": "The different events that can trigger a webhook"
},
"GenericEvent": {
"type": "object",
"properties": {
"event": {
"$ref": "#/components/schemas/WebhookEvents"
},
"eventTime": {
"description": "Time of the event.",
"type": "string",
"format": "date-time"
},
"fax": {
"$ref": "#/components/schemas/Fax"
}
}
},
"ServiceId": {
"x-PII": false,
"x-v1": true,
"readOnly": true,
"type": "string",
"example": "01GVRB50KEQFFE1SGMPFRNBG6J",
"description": "ID of the fax service used."
},
"FaxStatus": {
"type": "string",
"description": "The status of the fax",
"readOnly": true,
"enum": [
"QUEUED",
"IN_PROGRESS",
"COMPLETED",
"FAILURE"
],
"x-enumDescriptions": {
"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."
}
},
"CoverPageData": {
"type": "object",
"title": "Cover page data",
"description": "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](https://developers.sinch.com/docs/fax/api-reference/fax/cover-pages/). All keys used must be lower case.\n\n- `application/json` format: `\"coverPageData\": {\"customfield1\":\"customdata1\"}`\n- `multipart/form-data` format: `coverPageData[customfield1] = customdata1`",
"additionalProperties": {
"type": "string",
"x-additionalPropertiesName": "coverPageKey"
},
"example": {
"toName": "Acme Corp"
}
},
"Labels": {
"type": "object",
"title": "label",
"description": "You can use this to attach labels to your call that you can use in your applications. It is a key value store.\n\n- `application/json` format: `\"labels\": {\"label1\":\"value1\"}`\n- `multipart/form-data` format: `labels[label1] = value1`",
"additionalProperties": {
"type": "string",
"x-additionalPropertiesName": "labelKey"
},
"example": {
"use-case": "fraudPrevention",
"costCenter": "sales"
}
},
"PhoneNumber": {
"x-PII": true,
"x-v1": true,
"type": "string",
"format": "phoneNumber",
"description": "A phone number in [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) format, including the leading '+'.",
"example": "+15551235656"
},
"ProjectId": {
"type": "string",
"x-PII": false,
"x-v1": false,
"description": "The `Id` of the project associated with the call.",
"x-Internal": "to support future account keys",
"readOnly": true,
"example": "ae00f005-e392-44dc-b3f5-a657a2684dg3"
},
"Money": {
"description": "This is where we need description to be overridden by `$ref:` description",
"type": "object",
"readOnly": true,
"properties": {
"currencyCode": {
"readOnly": true,
"description": "The 3-letter currency code defined in ISO 4217.",
"type": "string",
"example": "USD"
},
"amount": {
"readOnly": true,
"description": "The amount with 4 decimals and decimal delimiter `.`.",
"type": "string",
"example": "0.0040"
}
}
},
"Resolution": {
"type": "string",
"description": "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": [
"FINE",
"SUPERFINE"
],
"x-enumDescriptions": {
"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."
}
},
"Pagination": {
"type": "object",
"readOnly": true,
"properties": {
"page": {
"readOnly": true,
"type": "integer",
"description": "Current page"
},
"totalPages": {
"readOnly": true,
"type": "integer",
"description": "Total number of pages."
},
"pageSize": {
"readOnly": true,
"type": "integer",
"description": "Number of items per page."
},
"totalItems": {
"type": "integer",
"readOnly": true,
"format": "int32",
"description": "Total size of the result."
}
}
},
"CreateDomainResponse": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "The result of the create domain operation.",
"example": "domain and route created"
},
"records": {
"type": "object",
"properties": {
"receivingRecords": {
"type": "array",
"description": "The receiving records of the domain.",
"items": {
"$ref": "#/components/schemas/ReceivingRecords"
}
},
"sendingRecords": {
"type": "array",
"description": "The sending records of the domain.",
"items": {
"$ref": "#/components/schemas/SendingRecords"
}
}
}
}
}
},
"ReceivingRecords": {
"type": "object",
"properties": {
"isActive": {
"type": "boolean",
"description": "True if the domain is active."
},
"cached": {
"type": "array",
"description": "Any cached value of the record.",
"items": {
"type": "string"
}
},
"priority": {
"type": "integer",
"description": "The priority for the record.",
"example": 10
},
"recordType": {
"type": "string",
"description": "The type of the record.",
"example": "TXT"
},
"valid": {
"type": "string",
"description": "The validity of the record.",
"enum": [
"valid",
"invalid"
],
"x-enumDescriptions": {
"valid": "The record is valid.",
"invalid": "The record is invalid."
},
"example": "valid"
},
"value": {
"type": "string",
"description": "The value of the record.",
"example": "mailgun.org"
}
}
},
"SendingRecords": {
"type": "object",
"properties": {
"isActive": {
"type": "boolean",
"description": "True if the domain is active."
},
"cached": {
"type": "array",
"description": "Any cached value of the record.",
"items": {
"type": "string"
}
},
"name": {
"type": "string",
"description": "The name of the domain record.",
"example": "my.domain.com"
},
"recordType": {
"type": "string",
"description": "The type of the record.",
"example": "TXT"
},
"valid": {
"type": "string",
"description": "The validity of the record.",
"enum": [
"valid",
"invalid"
],
"x-enumDescriptions": {
"valid": "The record is valid.",
"invalid": "The record is invalid."
},
"example": "valid"
},
"value": {
"type": "string",
"description": "The value of the record.",
"example": "mailgun.org"
}
}
},
"DomainsListResponse": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"domains": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Domain"
}
}
}
}
]
},
"Domain": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the domain.",
"example": "01K8BS9391KGN2Y36CDSNAVHNW"
},
"name": {
"type": "string",
"description": "The name of the domain.",
"example": "my.domain.com"
},
"receivingDnsRecord": {
"$ref": "#/components/schemas/ReceivingRecords"
},
"sendingDnsRecord": {
"$ref": "#/components/schemas/SendingRecords"
},
"serviceId": {
"type": "string",
"description": "The ID of the service to which the domain is attached.",
"example": "01H66TG3G97XH3GGVYP1NF7CYT"
},
"createdAt": {
"type": "string",
"description": "The timestamp on which the domain was created.",
"format": "date-time",
"example": "2025-10-24 18:56:42.787000+00:00"
},
"updatedAt": {
"type": "string",
"description": "The timestamp on which the domain was updated.",
"format": "date-time",
"example": "2025-10-24 19:11:50.235000+00:00"
},
"verified": {
"type": "boolean",
"description": "Flag that shows if the domain has been verified.",
"example": true
},
"routeId": {
"type": "string",
"description": "The route ID of the domain.",
"example": "68fbcbeb0a12858e880ffcea"
}
}
},
"DomainDetails": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the domain.",
"example": "01K8BS9391KGN2Y36CDSNAVHNW"
},
"isDisabled": {
"type": "boolean",
"description": "Flag that shows if the domain is disabled.",
"example": false
},
"name": {
"type": "string",
"description": "The name of the domain.",
"example": "my.domain.com"
},
"requireTls": {
"type": "boolean",
"description": "If set to true, this requires messages for the domain only be sent over a TLS connection. If a TLS connection cannot be established, Mailgun will not deliver the message. If set to false, Mailgun will still try and upgrade the connection, but if Mailgun cannot, the message will be delivered over a plaintext SMTP connection.",
"example": false,
"default": false
},
"skipVerification": {
"type": "boolean",
"description": "If set to true, the certificate and hostname will not be verified when trying to establish a TLS connection and Mailgun will accept any certificate during delivery of a message. If set to false, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection will not be established.",
"example": false,
"default": false
},
"smtpLogin": {
"type": "string",
"description": "SMTP server password for authentication.",
"example": ""
},
"spamAction": {
"type": "string",
"description": "Disabled, block or tag. Default to disabled. If disabled, no spam filtering will occur for inbound messages.",
"enum": [
"disabled",
"block",
"tag"
],
"x-enumDescriptions": {
"disabled": "No spam filtering will occur for inbound messages.",
"block": "Inbound spam messages will not be delivered.",
"tag": "Inbound messages will be tagged with a spam header."
},
"example": "disabled",
"default": "disabled"
},
"state": {
"type": "string",
"description": "The current verification status of the domain.",
"example": "active"
},
"type": {
"type": "string",
"description": "The classification of the domain.",
"enum": [
"custom",
"sandbox"
],
"x-enumDescriptions": {
"custom": "Domain is of custom type.",
"sandbox": "Domain is of sandbox type."
},
"example": "custom"
},
"useAutomaticSenderSecurity": {
"type": "boolean",
"description": "Enable Automatic Sender Security. This requires setting DNS CNAME entries for DKIM keys instead of a TXT record.",
"example": false,
"default": false
},
"webPrefix": {
"type": "string",
"description": "Sets your open, click and unsubscribe URLs domain name prefix. Links rewritten or added by Mailgun in your emails will look like ://./...",
"example": "email",
"default": "email"
},
"webScheme": {
"type": "string",
"enum": [
"http",
"https"
],
"x-enumDescriptions": {
"http": "Use http when opening URLs.",
"https": "Use https when opening URLs."
},
"description": "Sets your open, click and unsubscribe URLs to use http or https. Value either `http` or `https`. Defaults to `http`. In order for https to work, you must have a valid cert created for your domain.",
"example": "http",
"default": "http"
},
"wildcard": {
"type": "boolean",
"description": "Allows domain to accept inbound messages received on subdomains that have MX records pointed to Mailgun.",
"example": false,
"default": false
},
"encryptIncomingMessage": {
"type": "boolean",
"description": "Enable encrypting incoming messages for the given domain. This cannot be altered via API after being set for security purposes. Reach out to Support to disable if necessary.",
"example": false,
"default": false
},
"messageTtl": {
"type": "integer",
"description": "Specifies the time-to-live (TTL) in seconds for retrieving both incoming and outgoing messages. The maximum TTL value is determined by your subscription plan.",
"example": 259200
}
}
},
"DomainDetailsResponse": {
"type": "object",
"properties": {
"domain": {
"$ref": "#/components/schemas/DomainDetails"
},
"receivingDnsRecords": {
"type": "array",
"description": "The receiving records of the domain.",
"items": {
"$ref": "#/components/schemas/ReceivingRecords"
}
},
"sendingDnsRecords": {
"type": "array",
"description": "The sending records of the domain.",
"items": {
"$ref": "#/components/schemas/SendingRecords"
}
}
}
},
"VerifyDomainResponse": {
"type": "object",
"properties": {
"domains": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VerifyDomainObject"
}
}
}
},
"VerifyDomainDetails": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/DomainDetails"
}
],
"properties": {
"serviceId": {
"type": "string",
"description": "The service ID to which the domain is assigned.",
"example": "01H66TG3G97XH3GGVYP1NF7CYD"
},
"projectId": {
"type": "string",
"description": "The project ID to which the domain is assigned.",
"example": "5ff51b4c-7e9f-4acc-9f0e-6dd9559722e6"
}
}
},
"VerifyDomainObject": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "This message describes what is updated.",
"example": "Domain DNS records have been updated"
},
"domain": {
"$ref": "#/components/schemas/VerifyDomainDetails"
},
"receivingDnsRecords": {
"type": "array",
"description": "The receiving records of the domain.",
"items": {
"$ref": "#/components/schemas/ReceivingRecords"
}
},
"sendingDnsRecords": {
"type": "array",
"description": "The sending records of the domain.",
"items": {
"$ref": "#/components/schemas/SendingRecords"
}
}
}
},
"TemplatesDomainNameResponse": {
"type": "array",
"description": "An array of the named templates for the domain specified.",
"items": {
"$ref": "#/components/schemas/TemplateDomainItem"
}
},
"TemplateDomainItem": {
"type": "object",
"description": "The named templates.",
"properties": {
"name": {
"$ref": "#/components/schemas/TemplateName"
},
"createdAt": {
"type": "string",
"description": "The timestamp on which the template was created.",
"format": "date-time",
"example": "2025-10-24 19:11:50.235000+00:00"
},
"description": {
"type": "string",
"description": "The description for the template.",
"example": "Successful fax template"
}
}
},
"UpdateTemplateRequest": {
"type": "object",
"properties": {
"template": {
"type": "string",
"description": "The contents of the template. The following variables are available for you to use in templates:\n\n| Variable | Description |\n| -------- | ----------- |\n| id | The ID of the fax. |\n| from | The phone number sending the fax. |\n| to | The phone number receiving the fax. |\n| completedTime | The date and time that the fax was completed. |\n| numberOfPages | The number of pages included in the fax. |\n| currencyCode | The currency in which the fax was billed. |\n| amount | The total cost of the fax. |\n| retryCount | The number of times the fax was retried. |\n",
"example": "
Hi,
You have sent a successful fax to: {{to}}!
Fax Id:
{{id}}
From:
{{from}}
To:
{{to}}
Number of pages:
{{numberOfPages}}
Completed at:
{{completedTime}}
Price:
{{currencyCode}} {{amount}}
Thanks!
"
}
}
},
"TemplateByNameResponse": {
"type": "object",
"properties": {
"template": {
"type": "object",
"description": "The email template.",
"properties": {
"name": {
"$ref": "#/components/schemas/TemplateName"
},
"createdAt": {
"type": "string",
"description": "The timestamp on which the template was created.",
"format": "date-time",
"example": "2025-10-24 19:11:50.235000+00:00"
},
"id": {
"type": "string",
"description": "The ID of the template.",
"example": "8836986f-050c-4b2d-afb9-8069d1520b17"
},
"version": {
"type": "object",
"properties": {
"tag": {
"type": "string",
"description": "The tag for the template.",
"example": "initial"
},
"template": {
"type": "string",
"description": "The contents of the template.",
"example": "
Hi,
You have sent a successful fax to: {{to}}!
Fax Id:
{{id}}
From:
{{from}}
To:
{{to}}
Number of pages:
{{numberOfPages}}
Completed at:
{{completedTime}}
Price:
{{currencyCode}} {{amount}}
Thanks!
"
},
"createdAt": {
"type": "string",
"description": "The timestamp on which the template was created.",
"format": "date-time",
"example": "2025-10-24 19:11:50.235000+00:00"
},
"comment": {
"type": "string",
"description": "Optional field for comments if necessary.",
"example": ""
},
"active": {
"type": "boolean",
"description": "Displays whether the template is active or not.",
"example": true
},
"id": {
"type": "string",
"description": "The ID for the template version.",
"example": "fa01442c-e3d5-482b-be67-e3fdda931b00"
},
"headers": {
"type": "object",
"description": "Headers that are sent along with the template."
}
}
}
}
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"description": "HTTP status code or error code",
"readOnly": true,
"type": "integer",
"format": "int32",
"example": 400
},
"status": {
"description": "Response status name.",
"readOnly": true,
"type": "string",
"example": "INVALID_ARGUMENT"
},
"message": {
"type": "string",
"readOnly": true,
"description": "A developer-facing error message",
"example": "Bad request."
},
"details": {
"readOnly": true,
"description": "Details of the errors",
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ErrorDetail"
}
]
}
}
}
},
"ErrorDetail": {
"type": "object",
"anyOf": [
{
"$ref": "#/components/schemas/NotFoundDetail"
},
{
"$ref": "#/components/schemas/BadRequestDetail"
},
{
"$ref": "#/components/schemas/ErrorInfo"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"NotFound": "#/components/schemas/NotFoundDetail",
"BadRequest": "#/components/schemas/BadRequestDetail",
"ErrorInfo": "#/components/schemas/ErrorInfo"
}
}
},
"ErrorType": {
"readOnly": true,
"description": "Error type",
"type": "string",
"enum": [
"DOCUMENT_CONVERSION_ERROR",
"CALL_ERROR",
"FAX_ERROR",
"FATAL_ERROR",
"GENERAL_ERROR"
],
"x-enumDescriptions": {
"DOCUMENT_CONVERSION_ERROR": "A documentation conversion error.",
"CALL_ERROR": "A call error.",
"FAX_ERROR": "A fax error.",
"FATAL_ERROR": "A fatal error.",
"GENERAL_ERROR": "A general error."
}
},
"FaxErrors": {
"type": "object",
"anyOf": [
{
"$ref": "#/components/schemas/DocumentConversionError"
},
{
"$ref": "#/components/schemas/CallError"
},
{
"$ref": "#/components/schemas/FaxError"
}
],
"discriminator": {
"propertyName": "errorType",
"mapping": {
"DOCUMENT_CONVERSION_ERROR": "#/components/schemas/DocumentConversionError",
"CALL_ERROR": "#/components/schemas/CallError",
"FAX_ERROR": "#/components/schemas/FaxError"
}
},
"examples": [
{
"DocumentConversionError": null,
"summary": "Document conversion error",
"value": {
"errorType": "DOCUMENT_CONVERSION_ERROR",
"errorMessage": "There was a problem in converting and merging files to the output file format. Contact support.",
"errorCode": 4
}
},
{
"CallError": null,
"summary": "Call error",
"value": {
"errorType": "CALL_ERROR",
"errorMessage": "Busy",
"errorCode": 17
}
},
{
"FaxError": null,
"summary": "Fax error",
"value": {
"errorType": "FAX_ERROR",
"errorMessage": "Could not establish a connection to the fax server.",
"errorCode": 6
}
}
]
},
"FaxError": {
"type": "object",
"description": "A problem occurred during the fax communication process.",
"properties": {
"errorType": {
"description": "Type of error for the fax",
"type": "string",
"enum": [
"FAX_ERROR"
],
"x-enumDescriptions": {
"FAX_ERROR": "An error related to the fax."
},
"example": "FAX_ERROR"
},
"errorMessage": {
"description": "A developer-facing error message",
"type": "string",
"example": "Could not establish a connection to the fax server."
},
"errorCode": {
"type": "integer",
"description": "The error code returned describing the error of the call",
"enum": [
6,
7,
8,
10,
12,
13,
14,
18,
20,
21,
22,
25,
26,
28,
29,
31,
38,
40,
41,
44,
46,
48,
53,
60,
63,
68,
75,
76,
77,
79,
80,
82,
84,
113,
117,
119,
131,
132,
133
],
"x-enumDescriptions": {
"6": "There was an error communicating with the far side.",
"7": "Far end cannot receive at the size of image",
"8": "No response after sending a page",
"10": "Disconnected after permitted retries",
"12": "Received no response to DCS or TCF",
"13": "Timed out waiting for the first message",
"14": "Timed out waiting for initial communication",
"18": "Unexpected message received",
"20": "The HDLC carrier did not stop in a timely manner",
"21": "Received a DCN from remote after sending a page",
"22": "Received bad response to DCS or training",
"25": "Far end cannot receive at the resolution of the image",
"26": "The remote fax machine failed to respond",
"28": "Failed to train with any of the compatible modems",
"29": "Invalid response after sending a page",
"31": "Fax machine incompatibility",
"38": "The remote fax machine hung up before receiving fax",
"40": "Telephony error",
"41": "Unexpected DCN while waiting for DCS or DIS",
"44": "Telephony Error",
"46": "Insufficient funds to send fax and not able to auto recharge; There was a problem charging your credit card. Please check your payment information and try again.",
"48": "No answer (The Receiving Machine May Be Out Of Paper)",
"53": "Unexpected DCN after EOM or MPS sequence",
"60": "Transmission error after page break",
"63": "Fax protocol error",
"68": "Far end is not compatible",
"75": "Manually canceled by user",
"76": "Canceled automatically because timeout exceeded",
"77": "Timed out waiting for receiver ready (ECM mode)",
"79": "Can't cancel the fax, it's already complete!",
"80": "Received a DCN while waiting for a DIS",
"82": "There was an error communicating with the far side",
"84": "Unexpected command after page received",
"113": "The file for this fax has been deleted or is not accessible.",
"117": "No pages received",
"119": "User requested simulated faxError",
"131": "Incomplete transmission",
"132": "No fax tone detected",
"133": "Phone number is not permitted"
}
}
}
},
"CallError": {
"type": "object",
"description": "There was a problem with the phone line. The call could not be placed. Many times you can just try again",
"properties": {
"errorType": {
"description": "Type of error for the Call",
"type": "string",
"enum": [
"CALL_ERROR"
],
"x-enumDescriptions": {
"CALL_ERROR": "An error related to the call."
},
"example": "CALL_ERROR"
},
"errorMessage": {
"description": "A developer-facing error message",
"type": "string",
"example": "Busy"
},
"errorCode": {
"type": "integer",
"description": "The error code returned describing the error of the call.",
"enum": [
11,
15,
16,
17,
19,
30,
32,
34,
43,
49
],
"x-enumDescriptions": {
"11": "The call dropped prematurely",
"15": "Congestion",
"16": "Ring Timeout",
"17": "Busy",
"19": "Immediate Hangup",
"30": "No answer from a fax machine.",
"32": "Incompatible destination",
"34": "Phone number not operational",
"43": "Problem establishing connection",
"49": "The destination phone number Is Not active"
}
}
}
},
"DocumentConversionError": {
"type": "object",
"description": "Conversion errors usually occur when there is a problem with one of the files you posted.",
"properties": {
"errorType": {
"description": "Type of error for the Document conversion",
"type": "string",
"enum": [
"DOCUMENT_CONVERSION_ERROR"
],
"x-enumDescriptions": {
"DOCUMENT_CONVERSION_ERROR": "An error related to document conversion."
},
"example": "DOCUMENT_CONVERSION_ERROR"
},
"errorMessage": {
"description": "The error message",
"type": "string",
"example": "There was a problem in converting and merging files to the output file format. Contact support."
},
"errorCode": {
"type": "integer",
"description": "The error code returned during document conversion.",
"enum": [
4,
54,
55,
57,
69,
122,
128,
129,
130,
133
],
"x-enumDescriptions": {
"4": "There was a problem in converting and merging files to the output file format. Contact support.",
"54": "Could not access the url you provided. {contentUrl}",
"55": "The string_data URL you provided is invalid",
"57": "There was a problem storing the file you provided.",
"69": "There was a problem storing the file you provided.",
"122": "User simulated Document Conversion Error",
"128": "Could not determine mimetype for file.",
"129": "Mimetype not supported.",
"130": "Mimetype not supported: application/xml",
"133": "Failed to normalize PDF document"
}
}
}
},
"NotFoundDetail": {
"type": "object",
"description": "The request was malformed on one or more fields.",
"x-internal": "https://github.com/googleapis/googleapis/blob/f79d6e85a9a6b913a5e9cb0067e846e7f087dbc8/google/rpc/error_details.proto#L169",
"properties": {
"type": {
"type": "string",
"description": "The request was malformed on one or more properties.",
"readOnly": true,
"example": "NOT_FOUND",
"default": "BadRequest"
}
}
},
"BadRequestDetail": {
"type": "object",
"description": "The request was malformed on one or more fields.",
"x-internal": "https://github.com/googleapis/googleapis/blob/f79d6e85a9a6b913a5e9cb0067e846e7f087dbc8/google/rpc/error_details.proto#L169",
"properties": {
"type": {
"type": "string",
"description": "The request was malformed on one or more properties.",
"readOnly": true,
"example": "BadRequest",
"default": "BadRequest"
},
"fieldViolations": {
"description": "The field violation(s).",
"type": "array",
"items": {
"type": "object",
"readOnly": true,
"allOf": [
{
"$ref": "#/components/schemas/FieldViolation"
}
]
},
"example": [
{
"field": "to",
"description": "Phone number was not in the expected format."
}
]
}
}
},
"FieldViolation": {
"type": "object",
"properties": {
"field": {
"type": "string",
"readOnly": true,
"description": "Request field.",
"example": "to"
},
"description": {
"type": "string",
"readOnly": true,
"description": "Description of why the request field was considered invalid.",
"example": "Phone number was not in the expected format."
}
}
},
"ErrorInfo": {
"description": "Describes the cause of the error with structured details.\nExample of an error when trying to make a call to blocked destination:\n\n { \"reason\": \"DESTINATION_BLOCKED\"\n \"domain\": \"VOICE\"\n \"metadata\": {\n \"country\": \"Bermuda\",\n }\n }",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Describes the cause of the error with structured details.\nExample of an error when trying to make a call to blocked destination:\n\n```\n { \"reason\": \"DESTINATION_BLOCKED\"\n \"domain\": \"VOICE\"\n \"metadata\": {\n \"country\": \"Bermuda\",\n }\n }\n```",
"default": "ErrorInfo",
"example": "ErrorInfo"
},
"reason": {
"type": "string",
"description": "The reason of the error. This is a constant value that identifies the\nproximate cause of the error. Error reasons are unique. Max 63 characters and match\n /[A-Z0-9_]+/.",
"maxLength": 63
},
"domain": {
"type": "string",
"description": "Domain for error, for voice its always sinch.voice"
},
"metaData": {
"description": "Additional structured details about this error. key value pair of strings",
"type": "object"
}
}
}
},
"parameters": {
"Id": {
"in": "path",
"name": "id",
"required": true,
"description": "The ID of the fax.",
"schema": {
"$ref": "#/components/schemas/FaxId"
}
},
"Page": {
"in": "query",
"name": "page",
"description": "The page you want to retrieve returned from a previous List request, if any",
"schema": {
"type": "string"
}
},
"PageSize": {
"name": "pageSize",
"in": "query",
"description": "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.",
"schema": {
"type": "integer",
"maximum": 1000,
"minimum": 1
}
},
"Labels": {
"name": "labels",
"in": "query",
"schema": {
"$ref": "#/components/schemas/Labels"
}
},
"Format": {
"name": "format",
"in": "query",
"description": "If you include this parameter, you can export the list of faxes as a .csv file. Default value is `csv`",
"schema": {
"type": "string",
"enum": [
"csv"
],
"x-enumDescriptions": {
"csv": "This exports the list of faxes as a .csv file."
},
"example": "csv"
}
}
},
"securitySchemes": {
"WebhookBasicAuth": {
"type": "http",
"scheme": "basic",
"description": "You can validate whether a webhook is genuine by providing credentials you set and will check on your server side along with the callback URL, as in this example: `https://username:password@www.YourWebhookWebsite.com`"
},
"BasicAuth": {
"type": "http",
"scheme": "basic",
"description": "The user name and password is your keyId and key secret from the [Access keys sections](https://dashboard.sinch.com/settings/access-keys)"
},
"OAuth2": {
"type": "oauth2",
"description": "The user name and password is your key id and key secret from the [Access keys sections](https://dashboard.sinch.com/settings/access-keys)",
"flows": {
"clientCredentials": {
"tokenUrl": "https://auth.sinch.com/oauth2/token",
"scopes": {}
}
}
}
}
}
}