SCAN Form Vendor Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-scanform-vendor-response-schema.json",
  "title": "SCAN Form Vendor Response",
  "description": "Response for a SCAN Form request using the `application/vnd.usps.labels+json` or `application/vnd.usps.labels+xml` `Accept` header.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-scan-forms-openapi.yml#/components/schemas/SCANFormVendorResponse",
  "type": "object",
  "allOf": [
    {
      "$ref": "#/$defs/SCANFormMetaData"
    },
    {
      "type": "object",
      "properties": {
        "SCANFormImage": {
          "description": "Contains the Base64-encoded file contents of the SCAN Form image. Provided only when `imageInfo.imageType` is not `NONE`.",
          "type": "string",
          "format": "byte"
        }
      },
      "additionalProperties": true
    }
  ],
  "$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"
      ]
    },
    "DeprecatedLabelTypeResponse": {
      "type": "string",
      "deprecated": true,
      "description": "This field has been deprecated.  `labelType` can be updated through `imageInfo.labelType`.",
      "default": "8.5x11LABEL",
      "enum": [
        "8.5x11LABEL",
        "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
    },
    "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
        }
      ]
    },
    "SCANFormMetaData": {
      "type": "object",
      "description": "Metadata for the scan form",
      "properties": {
        "imageInfo": {
          "$ref": "#/$defs/ImageInfo"
        },
        "form": {
          "$ref": "#/$defs/Form"
        },
        "imageType": {
          "$ref": "#/$defs/DeprecatedImageType"
        },
        "labelType": {
          "$ref": "#/$defs/DeprecatedLabelTypeResponse"
        },
        "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."
        },
        "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": "SCAN Form shipment method used to populate tracking numbers into the SCAN FOrm.",
          "oneOf": [
            {
              "$ref": "#/$defs/LabelShipment"
            },
            {
              "$ref": "#/$defs/MIDShipment"
            },
            {
              "$ref": "#/$defs/ManifestMIDShipment"
            }
          ]
        },
        "manifestNumber": {
          "type": "string",
          "description": "The Electronic File Number (EFN) stored in the Shipping Services File that represents all the tracking numbers associated to a shipment."
        },
        "trackingNumbers": {
          "type": "array",
          "description": "Tracking numbers that were added to the SCAN Form.  For `MID` and `manifestMID` Shipment options, only eligible labels matching the `MID` or `manifestMID`, `mailingDate`, `entryFacilityZIPCode`, and `destinationEntryFacilityType` are added.",
          "items": {
            "type": "string"
          }
        },
        "fromAddress": {
          "$ref": "#/$defs/SCANFormAddress"
        }
      }
    }
  }
}