Container

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-container-schema.json",
  "title": "Container",
  "description": "containers",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-containers-openapi.yml#/components/schemas/Container",
  "required": [
    "MID",
    "destinationEntryFacilityType",
    "mailClass",
    "mailerName",
    "originAddress",
    "processingCategory",
    "sortType"
  ],
  "type": "object",
  "properties": {
    "containerID": {
      "maxLength": 34,
      "type": "string",
      "description": "Unique identifier for a container",
      "readOnly": true
    },
    "imageInfo": {
      "$ref": "#/$defs/ImageInfo"
    },
    "allowManifestedLabels": {
      "$ref": "#/$defs/AllowManifestedLabels"
    },
    "sortType": {
      "type": "string",
      "description": "The sort type of the container being shipped.",
      "enum": [
        "TRUCK_BEDLOAD",
        "PALLET",
        "SACK"
      ]
    },
    "trackingNumbers": {
      "minItems": 1,
      "type": "array",
      "description": "List of tracking numbers for the packages that are in the container.",
      "writeOnly": true,
      "items": {
        "type": "string"
      }
    },
    "destinationEntryFacilityType": {
      "type": "string",
      "description": "The facility type where the container will be sent to.\n\n`NONE` is the only `destinationEntryFacilityType` available for `mailClass` `PRIORITY_MAIL` and `USPS_GROUND_ADVANTAGE`.\n\n`NONE` cannot be used as a `destinationEntryFacilityType` for `mailClass` `PARCEL_SELECT`.\n\nNote:\n* Effective 01/18/2026: `DESTINATION_NETWORK_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is no longer eligible.\n* Effective 01/18/2026: (NSA Only) `DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is available as an option.",
      "enum": [
        "DESTINATION_NETWORK_DISTRIBUTION_CENTER",
        "DESTINATION_SECTIONAL_CENTER_FACILITY",
        "DESTINATION_DELIVERY_UNIT",
        "DESTINATION_SERVICE_HUB",
        "DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER",
        "NONE"
      ]
    },
    "destinationZIPCode": {
      "maxLength": 5,
      "minLength": 5,
      "pattern": "\\d{5}",
      "type": "string",
      "description": "A 5-digit ZIP Code serviced by the `destinationEntryFacilityType` the container is being sent to.  This is used to identify the Destination Entry Facility.  Required when `mailClass` is `PARCEL_SELECT`."
    },
    "mailClass": {
      "type": "string",
      "description": "The mail class of the items enclosed in the container.  Only one mail class can be nested in a single container.",
      "enum": [
        "PARCEL_SELECT",
        "USPS_GROUND_ADVANTAGE",
        "PRIORITY_MAIL"
      ]
    },
    "originFacility": {
      "$ref": "#/$defs/OriginFacility"
    },
    "originAddress": {
      "required": [
        "ZIPCode",
        "city",
        "state",
        "streetAddress"
      ],
      "allOf": [
        {
          "$ref": "#/$defs/DomesticAddress"
        }
      ]
    },
    "mailerName": {
      "type": "string",
      "description": "Name of the firm/business that is shipping the container."
    },
    "processingCategory": {
      "type": "string",
      "description": "The type of packages that will be nested to the container. `MIXED` is only available for `DESTINATION_DELIVERY_UNIT` and `DESTINATION_SERVICE_HUB` containers.\n\nNote:\n* `NON_MACHINABLE` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.",
      "enum": [
        "MACHINABLE",
        "MIXED",
        "NON_MACHINABLE",
        "NONSTANDARD"
      ]
    },
    "containerTopology": {
      "type": "string",
      "default": "NESTED",
      "enum": [
        "NESTED"
      ]
    },
    "MID": {
      "pattern": "^(\\d{6}|\\d{9})$",
      "type": "string",
      "description": "Mailer Identifier to use to create the container barcode."
    },
    "warnings": {
      "type": "array",
      "readOnly": true,
      "items": {
        "$ref": "#/$defs/ContainerWarnings"
      }
    },
    "mailingDate": {
      "$ref": "#/$defs/MailingDateOptions"
    }
  },
  "additionalProperties": true,
  "$defs": {
    "Address": {
      "title": "Address",
      "type": "object",
      "properties": {
        "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 the 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 the city name for the address.",
          "readOnly": true
        }
      },
      "additionalProperties": true,
      "description": "Address fields standard to all locations."
    },
    "AllowManifestedLabels": {
      "type": "boolean",
      "writeOnly": true,
      "description": "Allow labels that have manifested to be added to the container."
    },
    "ContainerWarnings": {
      "type": "object",
      "properties": {
        "warningCode": {
          "type": "string"
        },
        "warningDescription": {
          "type": "string"
        }
      }
    },
    "DomesticAddress": {
      "title": "Domestic Address",
      "additionalProperties": true,
      "description": "The address of the Business Mail Entry Unit (BMEU) or authorized acceptance location facility where the container is being entered.",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        },
        {
          "type": "object",
          "properties": {
            "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.  When `mailClass` is `PRIORITY_MAIL` or `USPS_GROUND_ADVANTAGE`, the `ZIPCode` will be used to determine the origin entry facility."
            },
            "ZIPPlus4": {
              "pattern": "\\d{4}",
              "type": [
                "string",
                "null"
              ],
              "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
        }
      ]
    },
    "FacilityNASS": {
      "description": "NASS Code of the Facility for Mail Entry. \n",
      "type": "string",
      "pattern": "^[A-Z0-9]{1,5}$"
    },
    "ImageInfo": {
      "title": "Image Info",
      "type": "object",
      "properties": {
        "imageType": {
          "type": "string",
          "description": "The type of label image requested.  If omitted then the default image type is PDF.\n\nNote:\n- When using `ZPL203DPI` or `ZPL300DPI` the image returned will be rotated 90 degrees and be 4x6 inches, instead of 6x4 inches.\n",
          "default": "PDF",
          "enum": [
            "PDF",
            "TIFF",
            "JPG",
            "PNG",
            "GIF",
            "SVG",
            "ZPL203DPI",
            "ZPL300DPI",
            "NONE"
          ]
        },
        "labelType": {
          "type": "string",
          "description": "Ability to select the label image size.  If omitted then the default label size is 6X4LABEL.\n * '6X4LABEL'",
          "default": "6X4LABEL",
          "enum": [
            "6X4LABEL"
          ]
        },
        "addZPLComments": {
          "type": "boolean",
          "default": false,
          "description": "Applicable only when `imageType` is `ZPL203DPI` or `ZPL300DPI`.  When `addZPLComments` is `true`, comments will be visible within the ZPL text response to the user to denote different sections of their label.  When `addZPLComments` is `false`, no comments will be included in the ZPL text response.  This will be ignored for any other `imageType`.\n\nExample of a ZPL comment: \n`^FX Start of label. 123e4567-e89b-12d3-a456-426614174000 ^FS`\n"
        }
      },
      "additionalProperties": false,
      "description": "Additional details used to determine how to generate the label image.",
      "writeOnly": true
    },
    "MailingDate": {
      "type": "string",
      "description": "The date package 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"
    },
    "MailingDateOptions": {
      "description": "The mailing date for when the container will be shipped, when\nincluded in the request all packages nested to the container will be\nupdated to align with the associated mailingDate. The mailing date may\nbe today plus 0 to 7 days in advance. If it is not provided it will\nbe set as today.\n",
      "type": "string",
      "oneOf": [
        {
          "$ref": "#/$defs/MailingDate"
        },
        {
          "$ref": "#/$defs/MailingDateTime"
        }
      ]
    },
    "MailingDateTime": {
      "type": "string",
      "description": "The date and time a package 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"
    },
    "OriginFacility": {
      "description": "Used to specify the facility for origin entry in place of assignment through `originAddress.ZIPCode`.  The mapped facility will be printed on the 99M label.  Can only be used with `mailClass` of `PRIORITY_MAIL` or `USPS_GROUND_ADVANTAGE`.\n",
      "oneOf": [
        {
          "$ref": "#/$defs/FacilityNASS"
        }
      ]
    }
  }
}