{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-change-of-address-search-request-schema.json",
  "title": "Change Of Address Search Request",
  "description": "User information to search for old and new address records",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-ncoa-openapi.yml#/components/schemas/ChangeOfAddressSearchRequest",
  "required": [
    "CRID",
    "IPAgreementID",
    "requestType"
  ],
  "type": "object",
  "properties": {
    "CRID": {
      "description": "ID used to identify Customers registered to use Web Service.  It represents a business at a location.",
      "allOf": [
        {
          "$ref": "#/$defs/CRID"
        }
      ]
    },
    "IPAgreementID": {
      "description": "IP Agreement ID used to identify Customers with an NCOA+ IP Agreement.",
      "allOf": [
        {
          "$ref": "#/$defs/IPAgreementID"
        }
      ]
    },
    "requestType": {
      "title": "Customer NCOA+ requestType which represents either a Mailer Insert or a Search flag",
      "maxLength": 12,
      "type": [
        "string",
        "null"
      ],
      "description": "RequestType indicates which action you want performed a MailerInsert or Search ",
      "pattern": "^(MailerInsert|Search)$"
    },
    "mailerListID": {
      "description": "Mailer List ID signifies the Customer/BALA/End User (List Owner) for whom the request is made.  BALA is a broker, agent, or list administrator.",
      "allOf": [
        {
          "$ref": "#/$defs/MailerListID"
        }
      ]
    },
    "mailerList": {
      "title": "The Mailer List information",
      "type": "object",
      "description": "The object that hold all the properties for Mailer List information.\nRequired fields for Mailer information\n- mailerCompany\n- mailerID or CRID\n- mailerNAICSCode\n- mailerCompanyAddress\n- mailerCompanyCity\n- mailerCompanyState\n- mailerCompanyZIP\n- activeThroughDate\n",
      "properties": {
        "mailerCompany": {
          "maxLength": 255,
          "type": [
            "string",
            "null"
          ],
          "description": "Name of the Mailer Company",
          "pattern": "^[a-zA-Z0-9\\s#./&()+-]+$"
        },
        "mailerID": {
          "maxLength": 9,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer ID Associated with License",
          "pattern": "^(\\d{6}|9\\d{8})$"
        },
        "CRID": {
          "$ref": "#/$defs/CRID"
        },
        "mailerNAICSCode": {
          "maxLength": 6,
          "type": [
            "string",
            "null"
          ],
          "description": "NAICS Code tied to nature of the work the company does",
          "pattern": "^\\d+$"
        },
        "mailerCompanyAddress": {
          "maxLength": 64,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Company Address",
          "pattern": "^[a-zA-Z0-9\\s\\.\\,#\\-/&]+$"
        },
        "mailerCompanyCity": {
          "maxLength": 28,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Company City",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "mailerCompanyState": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Company State",
          "pattern": "^[A-Z]{2}$"
        },
        "mailerCompanyZIP": {
          "maxLength": 5,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Company ZIP Code",
          "pattern": "^\\d{5}$"
        },
        "mailerCompanyAddon": {
          "maxLength": 4,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Company Zip Code +4",
          "pattern": "^\\d{4}$"
        },
        "mailerCompanyUrb": {
          "maxLength": 28,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Company Urbanization",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "mailerCompanyPhone": {
          "maxLength": 12,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Company Phone Number",
          "pattern": "^(\\d{10}|\\d{3}-\\d{3}-\\d{4})$"
        },
        "mailerCompanyUrl": {
          "maxLength": 255,
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "Mailer Company Website"
        },
        "mailerContactName": {
          "maxLength": 255,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Contact Name",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "mailerContactAddr": {
          "maxLength": 64,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Contact Address",
          "pattern": "^[a-zA-Z0-9\\s\\.\\,#\\-/&]+$"
        },
        "mailerContactCity": {
          "maxLength": 28,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Contact City",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "mailerContactState": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Contact State",
          "pattern": "^[A-Z]{2}$"
        },
        "mailerContactZIP": {
          "maxLength": 5,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Contact Zip Code",
          "pattern": "^\\d{5}$"
        },
        "mailerContactAddon": {
          "maxLength": 4,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Contact Zip Code +4",
          "pattern": "^\\d{4}$"
        },
        "mailerContactUrbanization": {
          "maxLength": 28,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Contact Urbanization",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "mailerContactPhone": {
          "maxLength": 12,
          "type": [
            "string",
            "null"
          ],
          "description": "Mailer Contact Phone Number",
          "pattern": "^(\\d{10}|\\d{3}-\\d{3}-\\d{4})$"
        },
        "activeThroughDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "-> The date in which this Mailer List is active through to perform change of address lookups."
        },
        "balaMailerID": {
          "maxLength": 9,
          "type": [
            "string",
            "null"
          ],
          "description": "Bala Mailer ID. BALA is a broker, agent, or list administrator that has a direct relationship with the licensee.",
          "pattern": "^(\\d{6}|9\\d{8})$"
        },
        "balaNAICSCode": {
          "maxLength": 6,
          "type": [
            "string",
            "null"
          ],
          "description": "NAICS Code tied to nature of the work the company does",
          "pattern": "^\\d+$"
        },
        "balaCompanyName": {
          "maxLength": 255,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Company Name",
          "pattern": "^[a-zA-Z0-9\\s#./&()+-]+$"
        },
        "balaCompanyAddress": {
          "maxLength": 64,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Company Address",
          "pattern": "^[a-zA-Z0-9\\s\\.\\,#\\-/&]+$"
        },
        "balaCompanyCity": {
          "maxLength": 28,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Company City",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "balaCompanyState": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Company State",
          "pattern": "^[A-Z]{2}$"
        },
        "balaCompanyZIP": {
          "maxLength": 5,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Company Zip Code",
          "pattern": "^\\d{5}$"
        },
        "balaCompanyAddon": {
          "maxLength": 4,
          "type": "string",
          "description": "bala Company ZIP Code +4",
          "pattern": "^\\d{4}$"
        },
        "balaCompanyUrbanization": {
          "maxLength": 28,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Company Urbanization",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "balaCompanyPhone": {
          "maxLength": 12,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Company Phone Number",
          "pattern": "^(\\d{10}|\\d{3}-\\d{3}-\\d{4})$"
        },
        "balaCompanyUrl": {
          "maxLength": 255,
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "bala Company Website"
        },
        "balaContactName": {
          "maxLength": 255,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Contact Name",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "balaContactAddress": {
          "maxLength": 64,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Contact Address",
          "pattern": "^[a-zA-Z0-9\\s\\.\\,#\\-/&]+$"
        },
        "balaContactCity": {
          "maxLength": 28,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Contact City",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "balaContactState": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Contact State",
          "pattern": "^[A-Z]{2}$"
        },
        "balaContactZIP": {
          "maxLength": 5,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Contact ZIP Code",
          "pattern": "^\\d{5}$"
        },
        "balaContactAddon": {
          "maxLength": 4,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Contact Zip Code +4",
          "pattern": "^\\d{4}$"
        },
        "balaContactUrbanization": {
          "maxLength": 28,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Contact Urbanization",
          "pattern": "^[a-zA-Z\\s]+$"
        },
        "balaContactPhone": {
          "maxLength": 12,
          "type": [
            "string",
            "null"
          ],
          "description": "bala Contact Phone Number",
          "pattern": "^(\\d{10}|\\d{3}-\\d{3}-\\d{4})$"
        },
        "balaBrokerIndicator": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Bala Broker Indicator denoting if bala information is present (Y or N)",
          "pattern": "^[YN]$",
          "default": "N"
        }
      },
      "additionalProperties": false
    },
    "nameAddresses": {
      "title": "Name Addresses",
      "type": "array",
      "description": "Utilize when searching for a List of Name/Business Addresses.\nAt this time only 1 Name and Address will be accepted per request.\n",
      "items": {
        "$ref": "#/$defs/NameAddress"
      },
      "minItems": 1,
      "maxItems": 1
    },
    "numberOfMonths": {
      "title": "Number of Months",
      "type": "integer",
      "minimum": 1,
      "maximum": 48,
      "description": "Number of Months for the request 1 THROUGH 48. Minimum of 1 month & Maximum of 48 months."
    }
  },
  "additionalProperties": false,
  "$defs": {
    "CRID": {
      "title": "Customer Registration ID",
      "maxLength": 18,
      "type": "string",
      "description": "Customer Registration ID used to identify a business at a location.",
      "pattern": "^\\d+$"
    },
    "IPAgreementID": {
      "title": "Customer NCOA+ IP Agreement ID",
      "maxLength": 10,
      "type": "string",
      "description": "IP Agreement ID used to identify Customers with an NCOA+ IP Agreement.",
      "pattern": "^[a-zA-Z0-9]*$"
    },
    "MailerListID": {
      "title": "Mailer List ID",
      "maxLength": 16,
      "type": "string",
      "description": "Mailer List ID signifies the Customer/BALA/End User (List Owner) for whom the request is made.",
      "pattern": "^[a-zA-Z0-9]*$"
    },
    "NameAddress": {
      "title": "The Addressee information",
      "type": "object",
      "properties": {
        "fullName": {
          "maxLength": 66,
          "type": [
            "string",
            "null"
          ],
          "description": "COA Full Name (Prefix, First Name, Middle Name, Last Name, Suffix)",
          "pattern": "^\\s*[a-zA-Z0-9#./&()+-][a-zA-Z0-9\\s#./&()+-]*$"
        },
        "streetAddress": {
          "description": "The number of a building along with the name of the road or street on which it is located.",
          "allOf": [
            {
              "$ref": "#/$defs/StreetAddress"
            }
          ]
        },
        "lastLine": {
          "maxLength": 42,
          "type": [
            "string",
            "null"
          ],
          "description": "City State ZIP Code",
          "pattern": "^[a-zA-Z0-9\\s,-]+$"
        },
        "urbanization": {
          "description": "Urbanization area, sector, or residential development for the address.",
          "allOf": [
            {
              "$ref": "#/$defs/Urbanization"
            }
          ]
        },
        "recordID": {
          "maxLength": 50,
          "type": [
            "string",
            "null"
          ],
          "description": "ID/Keyline/etc – anything to identify the customer record",
          "pattern": "^[a-zA-Z0-9\\s\\-/]*$"
        }
      },
      "description": "The name and address of the user to search for."
    },
    "StreetAddress": {
      "title": "Street Address",
      "maxLength": 64,
      "type": [
        "string",
        "null"
      ],
      "description": "The number of a building along with the name of the road or street on which it is located."
    },
    "Urbanization": {
      "title": "Urbanization",
      "maxLength": 28,
      "type": [
        "string",
        "null"
      ],
      "description": "An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico)"
    }
  }
}