SCAN Form

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-scanform-request-schema.json",
  "title": "SCAN Form",
  "description": "Information required to generate a SCAN Form.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-scan-forms-openapi.yml#/components/schemas/SCANFormRequest",
  "required": [
    "destinationEntryFacilityType",
    "entryFacilityZIPCode",
    "fromAddress",
    "mailingDate",
    "shipment"
  ],
  "type": "object",
  "properties": {
    "imageInfo": {
      "$ref": "#/$defs/ImageInfo"
    },
    "form": {
      "$ref": "#/$defs/Form"
    },
    "imageType": {
      "$ref": "#/$defs/DeprecatedImageType"
    },
    "labelType": {
      "$ref": "#/$defs/DeprecatedLabelType"
    },
    "mailingDate": {
      "type": "string",
      "format": "date",
      "description": "The date of mailing.  The date when the items in the associated SCAN Form will be dropped off at the Entry Facility.  All labels associated to the SCAN Form must have the same `mailingDate`, unless the `overwriteMailingDate` option is selected."
    },
    "overwriteMailingDate": {
      "$ref": "#/$defs/OverwriteMailingDate"
    },
    "entryFacilityZIPCode": {
      "pattern": "^\\d{5}$",
      "type": "string",
      "description": "The ZIP Code™ of the destination entry facility."
    },
    "destinationEntryFacilityType": {
      "$ref": "#/$defs/DestinationEntryFacilityType"
    },
    "shipment": {
      "type": "object",
      "description": "Method used to generate the SCAN Form.  SCAN Forms can be created by providing a list of tracking numbers to be added to the SCAN Form or by automatically pulling eligible labels in via the MID or Manifest MID.\n\n**Label Eligibility Rules**:\n* All labels on a single SCAN Form must have the same `entryFacilityZIPCode` and `destinationEntryFacilityType`.\n* All labels on a single SCAN Form must have the same `mailingDate`.  If unmanifested labels with different mail dates are to be added to the same SCAN Form, use `overwriteMailingDate` value of `true` to update the label mail dates.\n* Labels can only be added to a SCAN Form prior to the label being manifested.  For manifest scheduling, refer to the time tables listed in the Domestic Labels and International Labels APIs.\n* Labels that have already been added to a SCAN Form cannot be added to a second SCAN Form.\n* Labels that were created with the `imageType` `LABEL_BROKER` cannot be added to a SCAN Form.\n* Labels that were created for Smart/Parcel Locker delivery cannot be added to a SCAN Form.\n* Labels that were created using Extra Service Code `415` (USPS Label Delivery) cannot be added to a SCAN Form.\n",
      "oneOf": [
        {
          "$ref": "#/$defs/LabelShipment"
        },
        {
          "$ref": "#/$defs/MIDShipment"
        },
        {
          "$ref": "#/$defs/ManifestMIDShipment"
        }
      ]
    },
    "fromAddress": {
      "$ref": "#/$defs/SCANFormAddress"
    },
    "pickupConfirmationNumber": {
      "$ref": "#/$defs/PickupConfirmationNumber"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "DeprecatedImageType": {
      "type": "string",
      "deprecated": true,
      "description": "This field has been deprecated.  `imageType` can be updated through `imageInfo.imageType`.",
      "default": "PDF",
      "enum": [
        "PDF",
        "TIFF",
        "JPG",
        "PNG",
        "GIF",
        "SVG",
        "NONE"
      ]
    },
    "DeprecatedLabelType": {
      "type": "string",
      "deprecated": true,
      "description": "This field has been deprecated.  `labelType` can be updated through `imageInfo.labelType`.",
      "default": "8.5x11LABEL",
      "enum": [
        "8.5x11LABEL"
      ]
    },
    "DestinationEntryFacilityType": {
      "type": "string",
      "description": "Specifies the type of facility the mailpieces are being entered at.  All mailpieces on a single SCAN Form must be entered at the same facility and facility type.  A value of `NONE` cannot be used when shipping Parcel Select or USPS Connect Local items.",
      "enum": [
        "NONE",
        "DESTINATION_NETWORK_DISTRIBUTION_CENTER",
        "DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER",
        "DESTINATION_SECTIONAL_CENTER_FACILITY",
        "DESTINATION_DELIVERY_UNIT",
        "DESTINATION_SERVICE_HUB"
      ]
    },
    "DomesticAddress": {
      "title": "Domestic Address",
      "description": "Address fields for US locations",
      "type": "object",
      "properties": {
        "firstName": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "First Name corresponding to the address."
        },
        "lastName": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "Last Name corresponding to the address."
        },
        "firm": {
          "maxLength": 50,
          "minLength": 0,
          "type": "string",
          "description": "Firm corresponding to the address. Firm is required for all domestic addresses in international label requests due to customs form requirements."
        },
        "streetAddress": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "The number of a building along with the name of the road or street on which it is located."
        },
        "streetAddressAbbreviation": {
          "maxLength": 50,
          "minLength": 0,
          "type": "string",
          "description": "This is the abbreviation of street address line for the address.",
          "readOnly": true
        },
        "secondaryAddress": {
          "maxLength": 50,
          "type": "string",
          "description": "The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.  For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm)."
        },
        "cityAbbreviation": {
          "type": "string",
          "description": "This is the abbreviation of city name for the address.",
          "readOnly": true
        },
        "city": {
          "maxLength": 28,
          "minLength": 1,
          "type": "string",
          "description": "This is the city name of the address."
        },
        "state": {
          "maxLength": 2,
          "minLength": 2,
          "pattern": "^(AA|AE|AL|AK|AP|AS|AZ|AR|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MP|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VI|VA|WA|WV|WI|WY)$",
          "type": "string",
          "description": "This is two-character state code of the address."
        },
        "ZIPCode": {
          "pattern": "^\\d{5}$",
          "type": "string",
          "description": "This is the 5-digit ZIP code."
        },
        "ZIPPlus4": {
          "pattern": "^\\d{4}$",
          "type": "string",
          "description": "This is the ZIP+4 extension."
        },
        "urbanization": {
          "maxLength": 96,
          "type": "string",
          "description": "An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico)"
        }
      },
      "additionalProperties": true
    },
    "Form": {
      "type": "string",
      "description": "This field has been deprecated.  The type of SCAN Form will be dictated by the `imageInfo.labelType` requested.",
      "deprecated": true,
      "default": "5630",
      "enum": [
        "5630"
      ]
    },
    "ImageInfo": {
      "type": "object",
      "description": "Characteristics of the type of SCAN Form being requested.",
      "properties": {
        "imageType": {
          "description": "The type of SCAN Form image being requested. If omitted then the default image type is `PDF`.\n\nNote: \n- The `labelType` of `8.5X11LABEL` is not supported with the `imageType` of `ZPL203DPI` or `ZPL300DPI`.\n- `ZPL203DPI` and `ZPL300DPI` are only supported via `imageInfo.imageType`. The deprecated `imageType` field does not support these values.",
          "default": "PDF",
          "type": "string",
          "enum": [
            "PDF",
            "TIFF",
            "JPG",
            "PNG",
            "GIF",
            "SVG",
            "ZPL203DPI",
            "ZPL300DPI",
            "NONE"
          ]
        },
        "labelType": {
          "description": "Ability to select the SCAN Form image size.  If omitted then the default SCAN form size is `8.5X11LABEL`.\n\nNote: \n- The `8.5X11LABEL` format will generate SCAN Form type 5630, the `4X6LABEL` format will generate SCAN Form type 5630-S.",
          "default": "8.5X11LABEL",
          "type": "string",
          "enum": [
            "8.5X11LABEL",
            "4X6LABEL"
          ]
        }
      }
    },
    "LabelShipment": {
      "title": "Label Shipment",
      "type": "object",
      "required": [
        "trackingNumbers"
      ],
      "description": "label shipment",
      "properties": {
        "trackingNumbers": {
          "type": "array",
          "description": "Tracking numbers to be added to the SCAN Form.\n",
          "minItems": 1,
          "maxItems": 40000,
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "MIDShipment": {
      "title": "MID Shipment",
      "type": "object",
      "required": [
        "MID"
      ],
      "description": "MID Shipment",
      "properties": {
        "MID": {
          "pattern": "^(\\d{6}|\\d{9})$",
          "type": "string",
          "description": "MID to be used for SCAN Form generation.\n\nThe `MID` in the SCAN Form request will be matched against the `MID` provided in the Payment Authorization Token under the `LABEL_OWNER` role.  All eligible labels created using the provided `MID` for the requested `mailingDate`, `entryFacilityZIPCode`, and `destinationEntryFacilityType` will be added to the SCAN Form.\n"
        }
      },
      "additionalProperties": false
    },
    "ManifestMIDShipment": {
      "title": "Manifest MID Shipment",
      "type": "object",
      "required": [
        "manifestMID"
      ],
      "description": "Manifest for a MID Shipment",
      "properties": {
        "manifestMID": {
          "pattern": "^(\\d{6}|\\d{9})$",
          "type": "string",
          "description": "Manifest MID to be used for SCAN Form generation.\n\nThe `manifestMID` in the SCAN Form request will be matched against the `manifestMID` provided in the Payment Authorization Token under the `LABEL_OWNER` role.  All eligible labels created using the provided `manifestMID` for the requested `mailingDate`, `entryFacilityZIPCode`, and `destinationEntryFacilityType` will be added to the SCAN Form.\n"
        }
      },
      "additionalProperties": false
    },
    "OverwriteMailingDate": {
      "type": "boolean",
      "description": "Label Mailing Date Overwrite option.  If this value is set to `true`, the mailing dates for the packages contained within the SCAN Form will be overwritten with the `mailingDate` value provided in the SCAN Form request.  If this value is set to `false`, the mailing dates for the packages contained within the SCAN Form will not be updated and will use the values initially provided in the Label request.",
      "default": false
    },
    "PickupConfirmationNumber": {
      "title": "Pickup Confirmation Number",
      "type": "string",
      "description": "Confirmation number from Carrier Pickup.  Used to tie the SCAN Form to items in the pickup.\n\nThe confirmation number will be returned in the Carrier Pickup API response or in the Carrier Pickup confirmation email.\n",
      "pattern": "^[A-Z]{3}\\d{8,12}$"
    },
    "SCANFormAddress": {
      "title": "SCAN Form Address",
      "required": [
        "ZIPCode",
        "city",
        "state",
        "streetAddress"
      ],
      "additionalProperties": true,
      "description": "Location of the Shipper. Only domestic addresses are supported for this API.\n\nNote:\n* The `firstName` and `lastName` or `firm` are always required.\n",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticAddress"
        },
        {
          "type": "object",
          "properties": {
            "ignoreBadAddress": {
              "type": "boolean",
              "description": "Allows Non-Validated Origin Street Address. Enter `true` to bypass street address validation failures/errors or `false` if only validated addresses should be allowed. \n\n**Note:** Integrators are recommended to always use `false` to ensure no delivery issues. \n\nIn the event USPS cannot validate the street address, this tag will “bypass” address validation error when `true` is indicated to allow label creation which could impact delivery.\n"
            }
          },
          "additionalProperties": true
        }
      ]
    }
  }
}