{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/telnyx/json-schema/telnyx-send-fax-request-schema.json",
  "title": "Send fax request",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/telnyx-programmable-fax-commands-api-openapi.yml#/components/schemas/SendFaxRequest",
  "properties": {
    "black_threshold": {
      "default": 95,
      "description": "The black threshold percentage for monochrome faxes. Only applicable if `monochrome` is set to `true`.",
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "client_state": {
      "description": "Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.",
      "type": "string"
    },
    "connection_id": {
      "description": "The connection ID to send the fax with.",
      "type": "string"
    },
    "from": {
      "$ref": "#/$defs/From"
    },
    "from_display_name": {
      "description": "The `from_display_name` string to be used as the caller id name (SIP From Display Name) presented to the destination (`to` number). The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If ommited, the display name will be the same as the number in the `from` field.",
      "type": "string"
    },
    "media_name": {
      "$ref": "#/$defs/MediaName"
    },
    "media_url": {
      "$ref": "#/$defs/MediaUrl"
    },
    "monochrome": {
      "default": false,
      "description": "The flag to enable monochrome, true black and white fax results.",
      "type": "boolean"
    },
    "preview_format": {
      "default": "tiff",
      "description": "The format for the preview file in case the `store_preview` is `true`.",
      "enum": [
        "pdf",
        "tiff"
      ],
      "type": "string"
    },
    "quality": {
      "$ref": "#/$defs/Quality"
    },
    "store_media": {
      "default": false,
      "description": "Should fax media be stored on temporary URL. It does not support media_name, they can't be submitted together.",
      "type": "boolean"
    },
    "store_preview": {
      "default": false,
      "description": "Should fax preview be stored on temporary URL.",
      "type": "boolean"
    },
    "t38_enabled": {
      "default": true,
      "description": "The flag to disable the T.38 protocol.",
      "type": "boolean"
    },
    "to": {
      "$ref": "#/$defs/To"
    },
    "webhook_url": {
      "description": "Use this field to override the URL to which Telnyx will send subsequent webhooks for this fax.",
      "type": "string"
    }
  },
  "required": [
    "connection_id",
    "from",
    "to"
  ],
  "type": "object",
  "$defs": {
    "From": {
      "description": "The phone number, in E.164 format, the fax will be sent from.",
      "type": "string"
    },
    "MediaName": {
      "description": "The media_name used for the fax's media. Must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. media_name and media_url/contents can't be submitted together.",
      "type": "string"
    },
    "MediaUrl": {
      "description": "The URL (or list of URLs) to the PDF used for the fax's media. media_url and media_name/contents can't be submitted together.",
      "type": "string"
    },
    "Quality": {
      "default": "high",
      "description": "The quality of the fax. The `ultra` settings provides the highest quality available, but also present longer fax processing times. `ultra_light` is best suited for images, wihle `ultra_dark` is best suited for text.",
      "enum": [
        "normal",
        "high",
        "very_high",
        "ultra_light",
        "ultra_dark"
      ],
      "type": "string"
    },
    "To": {
      "description": "The phone number, in E.164 format, the fax will be sent to or SIP URI",
      "type": "string"
    }
  }
}