{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/sinch/main/json-schema/sinch-fax-schema.json",
  "title": "Fax",
  "x-generated": "2026-10-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/sinch-fax-api-openapi.yml#/components/schemas/Fax",
  "type": "object",
  "properties": {
    "id": {
      "readOnly": true,
      "allOf": [
        {
          "$ref": "#/$defs/FaxId"
        }
      ]
    },
    "direction": {
      "allOf": [
        {
          "$ref": "#/$defs/FaxDirection"
        }
      ],
      "readOnly": true
    },
    "from": {
      "allOf": [
        {
          "$ref": "#/$defs/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": "#/$defs/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. Fetched documents must be one of the following file types: `.docx`, `html.`, `.jpg`, `.pdf`, `.png`, `.tif`, `.txt`."
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "format": "url"
          },
          "description": "Multiple URLs. Fetched documents must be one of the following file types: `.docx`, `html.`, `.jpg`, `.pdf`, `.png`, `.tif`, `.txt`."
        }
      ],
      "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/\"]`"
    },
    "numberOfPages": {
      "type": "integer",
      "readOnly": true,
      "description": "The number of pages in the fax."
    },
    "status": {
      "$ref": "#/$defs/FaxStatus"
    },
    "price": {
      "description": "The total price for this fax. This field is populated after the final fax price is calculated.",
      "allOf": [
        {
          "$ref": "#/$defs/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": "#/$defs/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
    },
    "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": "#/$defs/Labels"
        }
      ]
    },
    "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"
    },
    "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": "#/$defs/ImageConversionMethod"
    },
    "errorType": {
      "readOnly": true,
      "allOf": [
        {
          "$ref": "#/$defs/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": "boolean",
      "description": "Only shown on the fax result. This indicates if the content of the fax is stored with Sinch. (true or false)"
    },
    "resolution": {
      "$ref": "#/$defs/Resolution"
    },
    "coverPageId": {
      "type": "string",
      "description": "The cover page id you want to use for the fax"
    },
    "coverPageData": {
      "$ref": "#/$defs/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
    },
    "fromCountry": {
      "readOnly": true,
      "type": "string",
      "description": "The country code in ISO 3166-1 alpha-2 format of the number sending the fax."
    },
    "toCountry": {
      "readOnly": true,
      "type": "string",
      "description": "The country code in ISO 3166-1 alpha-2 format of the number receiving the fax."
    },
    "projectId": {
      "readOnly": true,
      "x-version": 1,
      "allOf": [
        {
          "$ref": "#/$defs/ProjectId"
        }
      ]
    },
    "serviceId": {
      "readOnly": false,
      "x-version": 1,
      "allOf": [
        {
          "$ref": "#/$defs/ServiceId"
        }
      ]
    }
  },
  "$defs": {
    "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"
        }
      }
    },
    "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"
      }
    },
    "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."
      }
    },
    "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."
      }
    },
    "FaxId": {
      "type": "string",
      "readOnly": true,
      "description": "The id of a fax"
    },
    "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."
      }
    },
    "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"
    },
    "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"
      }
    },
    "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"
        },
        "amount": {
          "readOnly": true,
          "description": "The amount with 4 decimals and decimal delimiter `.`.",
          "type": "string"
        }
      }
    },
    "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 '+'."
    },
    "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
    },
    "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."
      }
    },
    "ServiceId": {
      "x-PII": false,
      "x-v1": true,
      "readOnly": true,
      "type": "string",
      "description": "ID of the fax service used."
    }
  }
}