{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-address-subscription-schema.json",
  "title": "Subscription",
  "description": "Subscription for the Change of address to recieve notifications for.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-subscriptions-addresses-openapi.yml#/components/schemas/AddressSubscription",
  "allOf": [
    {
      "$ref": "#/$defs/Subscription"
    },
    {
      "required": [
        "filterProperties"
      ],
      "type": "object",
      "properties": {
        "filterProperties": {
          "description": "The filters that should be applied to the subscription. The structure of this property will change dependent on the type of subscription a client is signing up for.",
          "type": "object",
          "properties": {
            "subscriptionTTL": {
              "$ref": "#/$defs/SubscriptionTTL"
            },
            "CRID": {
              "$ref": "#/$defs/CRID"
            },
            "address": {
              "$ref": "#/$defs/Address"
            }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    }
  ],
  "$defs": {
    "Address": {
      "title": "Address",
      "type": "object",
      "properties": {
        "streetAddress": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "pattern": "^[A-Za-z0-9\\s,.]+$",
          "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",
          "pattern": "^[A-Za-z0-9\\s,.]+$",
          "description": "This is the abbreviation of the primary street address line for the address.",
          "readOnly": true
        },
        "secondaryAddress": {
          "maxLength": 50,
          "type": "string",
          "pattern": "^[A-Za-z0-9\\s,.]+$",
          "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)."
        },
        "city": {
          "maxLength": 28,
          "minLength": 1,
          "type": "string",
          "pattern": "^[A-Za-z\\s]+$",
          "description": "This is the city name of the address."
        },
        "state": {
          "$ref": "#/$defs/State"
        },
        "ZIPCode": {
          "pattern": "\\d{5}",
          "type": "string",
          "description": "This is the 5-digit ZIP code."
        },
        "urbanization": {
          "maxLength": 96,
          "type": "string",
          "pattern": "^[A-Za-z\\s]+$",
          "description": "An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico)."
        }
      },
      "additionalProperties": true,
      "description": "Address fields standard to all locations."
    },
    "CRID": {
      "title": "CRID",
      "maxLength": 25,
      "type": "string",
      "description": "Customer Registration ID.",
      "pattern": "^\\d+$"
    },
    "EmailNotification": {
      "type": "object",
      "description": "Email notification recipient details.",
      "properties": {
        "email": {
          "maxLength": 50,
          "type": "string",
          "description": "E-mail address of recipient. Valid e-mail addresses must be used used for notifications via email. ",
          "format": "email"
        }
      }
    },
    "State": {
      "title": "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": "The two-character state code."
    },
    "Subscription": {
      "title": "Subscription",
      "required": [
        "adminNotification",
        "listenerURL",
        "secret"
      ],
      "type": "object",
      "properties": {
        "SubscriptionId": {
          "type": "string",
          "description": "Unique Identifier created for this Subscription.",
          "pattern": "^[A-Za-z0-9\\-]+$",
          "readOnly": true
        },
        "listenerURL": {
          "type": "string",
          "description": "Customer URL in which subscription data will be sent. You can parse the data received on the server URL, and you can call back to the  API for the full detailed set of events.",
          "maxLength": 200,
          "format": "uri"
        },
        "secret": {
          "maxLength": 32,
          "minLength": 32,
          "type": "string",
          "pattern": "^[A-Za-z0-9\\-]+$",
          "description": "Customer supplied secret USPS will use to create a hash value.  The hash will be provided in the Notification payload. USPS will use the SHA-256 algorithm to create the hash value."
        },
        "status": {
          "type": "string",
          "description": "Current status of the subscription.  USPS will post notifications to the supplied listenerURL.  If the listenerURL cannot be reached or is invalid, USPS will change the status of the subscription to SUSPENDED.  The customer has the option of changing the status to DISABLED.  It is recommended the customer change the status to DISABLED if they know their endpoint will not be active, i.e operational maintenance.",
          "enum": [
            "DISABLED",
            "ENABLED",
            "SUSPENDED"
          ]
        },
        "statusReason": {
          "type": "string",
          "description": "When status is suspended the Status Reason will return why it was suspended",
          "pattern": "^[A-Za-z0-9\\s,.-]+$",
          "readOnly": true
        },
        "adminNotification": {
          "maxItems": 3,
          "minItems": 1,
          "type": "array",
          "description": "Customer can supply an email address to receive important updates on the status and events related to the subscription.",
          "items": {
            "$ref": "#/$defs/EmailNotification"
          }
        },
        "creationTimestamp": {
          "type": "string",
          "description": "When the subscription was originally created.",
          "format": "date-time",
          "readOnly": true,
          "minLength": 1,
          "maxLength": 50
        },
        "statusChangeTimestamp": {
          "type": "string",
          "description": "Time when the status was last changed",
          "format": "date-time",
          "readOnly": true
        },
        "expirationTimestamp": {
          "type": "string",
          "description": "When the subscription expires.",
          "format": "date-time",
          "readOnly": true
        }
      },
      "additionalProperties": true,
      "description": "Subscription for the Change of Address data the consumer is receiving."
    },
    "SubscriptionTTL": {
      "title": "Time to Live",
      "type": "integer",
      "description": "Indicates how long to keep the subscription active."
    }
  }
}