Indicia Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-indicia-request-schema.json",
  "title": "Indicia Request",
  "description": "Indicia request for letters, flats, and cards First-Class Mail International mailings.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-international-labels-openapi.yml#/components/schemas/IndiciaRequest",
  "required": [
    "indiciaDescription"
  ],
  "type": "object",
  "properties": {
    "indiciaDescription": {
      "$ref": "#/$defs/IndiciaRequestDescription"
    },
    "imageInfo": {
      "type": "object",
      "properties": {
        "receiptOption": {
          "type": "string",
          "description": "Indicia & Receipt print out options.\n\nEnter `SEPARATE_PAGE` to print the Indicia and the Receipt on separate pages. Enter `NONE` to print the Indicia only and no Receipt.\n",
          "default": "NONE",
          "enum": [
            "SEPARATE_PAGE",
            "NONE"
          ]
        },
        "imageType": {
          "type": "string",
          "description": "The type of indicia image requested.  If omitted then the default image type is PDF.",
          "default": "PDF",
          "enum": [
            "PDF",
            "TIFF",
            "JPG",
            "PNG",
            "GIF",
            "SVG"
          ]
        },
        "labelType": {
          "type": "string",
          "description": "Ability to select the indicia image size.  If omitted then the default indicia size is 2X1.5LABEL.\n",
          "default": "2X1.5LABEL",
          "enum": [
            "2X1.5LABEL"
          ]
        }
      },
      "additionalProperties": false,
      "description": "Additional details used to determine how to generate the indicia image."
    }
  },
  "additionalProperties": true,
  "$defs": {
    "IndiciaRequestDescription": {
      "title": "Indicia Request Description",
      "description": "The `IndiciaRequestDescription` object defines the physical dimensions, mailing date, processing category, and weight required for processing a First-Class Mail International letter, flat, or card.\n",
      "required": [
        "height",
        "length",
        "mailingDate",
        "processingCategory",
        "destinationCountryCode",
        "thickness",
        "weight"
      ],
      "type": "object",
      "properties": {
        "processingCategory": {
          "type": "string",
          "description": "* LETTERS          \n\n  To be eligible for mailing at the price for letters, a piece must be:\n    * Rectangular\n    * At least 3-1/2 inches high x 5 inches long x 0.007 inch thick.\n    * No more than 6-1/8 inches high x 11-1/2 inches long x 1/4 inch thick.\n\n  For additional information on letters, please refer to the [Postal Explorer](https://pe.usps.com/businessmail101?ViewName=Letters) and [International Mail Manual](https://pe.usps.com/text/imm/immc2_017.htm#:~:text=241.21%20Physical%20Standards%20%E2%80%94%20Letters).\n\n* FLATS \n\n  The Postal Service uses the word \"flats\" to refer to large envelopes, newsletters, and magazines. The words large envelopes and flats are used interchangeably. Whatever you call them, flats must:\n\n    * Have one dimension that is greater than 6-1/8 inches high OR 11-½ inches long OR ¼ inch thick.\n    * Be no more than 12 inches high x 15 inches long x ¾ inch thick.\n\n  For additional information on flats, please refer to the [Postal Explorer](https://pe.usps.com/businessmail101?ViewName=Flats) and the [International Mail Manual](https://pe.usps.com/text/imm/immc2_017.htm#:~:text=241.23%20Physical%20Standards%20%E2%80%94%20Large%20Envelopes%20(Flats)).\n\n* CARDS \n\n  To be eligible for mailing at the price for postcards, a piece must be:\n    * Rectangular\n    * At least 3-1/2 inches high x 5 inches long x 0.007 inch thick.\n    * No more than 4-1/4 inches high x 6 inches long x 0.016 inch thick.\n\n  For additional information on postcards, please refer to the [Postal Explorer](https://pe.usps.com/businessmail101?ViewName=Cards) and the [International Mail Manual](https://pe.usps.com/text/imm/immc2_017.htm#:~:text=241.22%20Physical%20Standards%20%E2%80%94%20Cards).\n",
          "enum": [
            "LETTERS",
            "FLATS",
            "CARDS"
          ]
        },
        "weight": {
          "minimum": 0,
          "exclusiveMinimum": true,
          "type": "number",
          "description": "The letter/flat/card weight, in ounces. The maximum weight of a letter or card is 3.5 oz and the maximum weight of a flat is 13 oz."
        },
        "mailingDate": {
          "$ref": "#/$defs/MailingDateIndiciaOptions"
        },
        "length": {
          "minimum": 0,
          "exclusiveMinimum": true,
          "type": "number",
          "description": "The letter/flat/card length in inches.  For  `LETTERS` and `CARDS` the length is the dimension parallel to the delivery address as read. For  `FLATS` the length is the longest dimension.",
          "format": "double"
        },
        "height": {
          "minimum": 0,
          "exclusiveMinimum": true,
          "type": "number",
          "description": "The letter/flat/card height in inches.  The height is the dimension perpendicular to the length.",
          "format": "double"
        },
        "thickness": {
          "minimum": 0,
          "exclusiveMinimum": true,
          "type": "number",
          "description": "The letter/flat/card thickness in inches. The minimum dimension is always the thickness.",
          "format": "double"
        },
        "destinationCountryCode": {
          "type": "string",
          "pattern": "[A-Z]{2}",
          "minLength": 2,
          "maxLength": 2,
          "description": "The 2-digit country code of the destination."
        },
        "nonMachinableIndicators": {
          "type": "object",
          "description": "Set of boolean indicators used to determine whether a letter qualifies as nonmachinable.",
          "properties": {
            "isPolybagged": {
              "type": "boolean",
              "description": "Is the letter/flat/card polybagged, polywrapped, enclosed in any plastic material, or has an exterior surface made of a material that is not paper. Windows in envelopes made of paper do not make mailpieces nonmachinable. Attachments allowable under applicable eligibility standards do not make mailpieces nonmachinable.",
              "default": false
            },
            "hasClosureDevices": {
              "type": "boolean",
              "description": "Does the letter/flat/card have clasps, strings, buttons, or similar closure devices.",
              "default": false
            },
            "hasLooseItems": {
              "type": "boolean",
              "description": "Does the letter/flat/card contain items such as pens, pencils, keys, or coins that cause the thickness of the mailpiece to be uneven; or loose keys or coins or similar objects not affixed to the contents within the mailpiece. Loose items may cause a letter to be nonmailable when mailed in paper envelopes; (see [DMM 601.3.3](https://pe.usps.com/text/dmm300/601.htm#ep1196660)).",
              "default": false
            },
            "isRigid": {
              "type": "boolean",
              "description": "Is the letter/flat/card too rigid (does not bend easily when subjected to a transport belt tension of 40 pounds around an 11-inch diameter turn).",
              "default": false
            },
            "isSelfMailer": {
              "type": "boolean",
              "description": "Is the letter/flat/card a self-mailer that is not prepared according to [DMM 201.3.14](https://pe.usps.com/text/dmm300/201.htm#ep1079302).",
              "default": false
            },
            "isBooklet": {
              "type": "boolean",
              "description": "Is the letter/flat/card a booklet that is not prepared according to [DMM 201.3.16](https://pe.usps.com/text/dmm300/201.htm#ep1092751).",
              "default": false
            }
          },
          "additionalProperties": false
        }
      }
    },
    "MailingDateIndicia": {
      "type": "string",
      "description": "The date the letter, flat, or card will be mailed. The mailing date may be today plus 0 to 7 days in advance. Enter the date in the full-date notation as defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).",
      "format": "date"
    },
    "MailingDateIndiciaOptions": {
      "type": "string",
      "description": "The date or date and time the letter, flat, or card will be mailed. Accepts either a date-only format or a date-time format. The mailing date may be today plus 0 to 7 days in advance.",
      "oneOf": [
        {
          "$ref": "#/$defs/MailingDateIndicia"
        },
        {
          "$ref": "#/$defs/MailingDateTimeIndicia"
        }
      ]
    },
    "MailingDateTimeIndicia": {
      "type": "string",
      "description": "The date and time the letter, flat, or card will be mailed. The mailing date may be today plus 0 to 7 days in advance. Enter the date in the date-time notation as defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).",
      "format": "date-time"
    }
  }
}