{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-records-response-schema.json",
  "title": "Records Response",
  "description": "The Returned List of records",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-ncoa-openapi.yml#/components/schemas/RecordsResponse",
  "type": "object",
  "properties": {
    "numberOfMonths": {
      "type": "integer",
      "maximum": 48,
      "minimum": 1,
      "description": "Number of months passed for for Change of Address"
    },
    "recordCount": {
      "title": "Number of Records",
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Number of Records in records Array returned to customer."
    },
    "COABeyondMonthsCount": {
      "title": "Number of Records outside requested number of Months",
      "type": "integer",
      "description": "Number of Records matched with a new address but outside requested number of Months.",
      "minimum": 0,
      "maximum": 200
    },
    "COAMatchCount": {
      "title": "Number of Records returning a new address",
      "type": "integer",
      "description": "Number of Records returning a new address (within requested number of Months).",
      "minimum": 0,
      "maximum": 200
    },
    "COANoMatchCount": {
      "title": "Number of Records returned with no COA",
      "type": "integer",
      "description": "Number of Records with no COA found on file.",
      "minimum": 0,
      "maximum": 200
    },
    "COAFoundCount": {
      "title": "Number of Records returned for matching COA but no new address",
      "type": "integer",
      "description": "Number of Records matched but no new address was available (e.g., MLNA, BCNO, new side wouldn't +4 code).",
      "minimum": 0,
      "maximum": 200
    },
    "COANotAllowedMatchCount": {
      "title": "Number of Records returned for COA match not allowed",
      "type": "integer",
      "description": "Number of Records returned for COA match not allowed (e.g., middle name mismatch, conflicting directions, etc).",
      "minimum": 0,
      "maximum": 200
    },
    "records": {
      "description": "Contains the records",
      "type": "array",
      "minItems": 0,
      "items": {
        "$ref": "#/$defs/Records"
      }
    }
  },
  "$defs": {
    "AddressObject": {
      "title": "Address Information",
      "required": [
        "address",
        "returnCode"
      ],
      "type": "object",
      "properties": {
        "returnCode": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "The return code from the address match. * `32` - Default Match * `31` - Single Match * `22` - Multiple Response Match * `21` - Address Not Found * `13` - Invalid City * `12` - Invalid State Code * `11` - Invalid ZIP Code * `10` - Invalid Address"
        },
        "returnCodeText": {
          "type": "string",
          "minLength": 0,
          "maxLength": 255,
          "description": "This is a description of the return code\n* \"Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address\"\n* \"Single Response – exact match\"\n* \"Multiple addresses were found for the information you entered, and no default exists.\"\n* \"Address Not Found\"\n* \"Invalid City\"\n* \"Invalid State Code\"\n* \"Invalid ZIP Code\"\n* \"Invalid Address\"\n"
        },
        "footnotes": {
          "type": [
            "string",
            "null"
          ],
          "description": "The Address Matching Engine (AME) footnotes.",
          "maxLength": 2
        },
        "address": {
          "description": "Contains the address",
          "type": "object",
          "allOf": [
            {
              "$ref": "#/$defs/DomesticAddress"
            }
          ]
        },
        "countyName": {
          "maxLength": 25,
          "minLength": 0,
          "type": "string",
          "description": "This is the county name associated with the delivery point (values unspecified)."
        },
        "carrierRoute": {
          "maxLength": 4,
          "type": [
            "string",
            "null"
          ],
          "description": "Carrier Route ID"
        },
        "recordType": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Record Type"
        },
        "DPVConfirmation": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Delivery Point Verification (DPV®) Return Code confirmation for address (Y/S/D/N)"
        },
        "DPVBusiness": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is a business (Y/N)"
        },
        "DPVCMRA": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is a Commercial Mail Receiving Agency (CMRA) (Y/N)"
        },
        "DPVDrop": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is a drop - mail is dropped by USPS for further distribution (Y/N)"
        },
        "DPVEducational": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is an Educational location (Y/N)"
        },
        "DPVDropCount": {
          "maxLength": 3,
          "type": [
            "string",
            "null"
          ],
          "description": "Drop Count - number of customers serviced where mail is dropped by USPS (001-999)"
        },
        "DPVLACS": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is an old side LACS address (Y/N)"
        },
        "DPVNoDoorDelivery": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "No door delivery flag - for situations where door is not accessible (Y/N)"
        },
        "DPVNostatReasonCode": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "Nostat reason code - 01-06 reasons that a delivery point is not counted for statistical purposes"
        },
        "DPVNostatReasonCodeDesc": {
          "type": "string",
          "description": "Indicates the reason description for nostat flag. * \"IDA (Internal Drop Address)\" * \"CDS Nostat\" * \"CMZ Nostat\" * \"Regular Nostat\" * \"Secondary Required\"",
          "enum": [
            "INTERNAL_DROP_ADDRESS",
            "CDS_NOSTAT",
            "CMZ_NOSTAT",
            "REGULAR_NOSTAT",
            "SECONDARY_REQUIRED"
          ]
        },
        "DPVSeasonal": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is seasonal - aka snowbird (Y/N)"
        },
        "DPVThrowback": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Throwback Flag - mail is delivered to a PO Box instead of this address (Y/N)"
        },
        "DPVNoSecureLocation": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "No secure Location flag - address has been flagged as such"
        },
        "DPVVacant": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is vacant (Y/N)"
        },
        "DPVNostat": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Nostat Flag - Not counted for statistical purposes (Y/N)"
        },
        "DPVNonDeliveryDaysFlag": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Non-delivery days flag - If 'Y' there are day(s) that mail is not delivered."
        },
        "DPVNonDeliveryDaysValues": {
          "maxLength": 255,
          "type": [
            "string",
            "null"
          ],
          "description": "Non-delivery days values - comma-delimited days that mail is not delivered."
        },
        "DPVCurbDelivery": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is Curb type of delivery (Y/N)"
        },
        "DPVNDCBUDelivery": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is NDCBU type of delivery (Y/N)"
        },
        "DPVCentralBoxDelivery": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is Central Box type of delivery (Y/N)"
        },
        "DPVOtherDelivery": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address is Other type of delivery (Y/N)"
        },
        "DPVDeliveryType": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Address Delivery Type of 1 - 4"
        },
        "DPVEnhancedConfirmation": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Enhanced DPV Confirmation Code - Indicates whether all the information needed to deliver to this address is present."
        },
        "DPVFootnotes": {
          "maxLength": 10,
          "type": [
            "string",
            "null"
          ],
          "description": "DPV Footnotes"
        },
        "DPVPBSA": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "Indicates a PO Box Street Address (Y/N)"
        },
        "DPVFalseConfirmation": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "False Confirmation Indicator - If 'Y' the address is flagged as a false confirmation."
        },
        "DPVUsageCode": {
          "maxLength": 1,
          "type": "string",
          "description": "DPV Usage Code - indicates the type of location for the address. A - Residential B - Business C - Mixed, mostly Residential D - Mixed, mostly Business G - General Delivery [Space] - Unknown",
          "enum": [
            "A",
            "B",
            "C",
            "D",
            "G",
            " "
          ]
        },
        "foreign1": {
          "maxLength": 37,
          "type": [
            "string",
            "null"
          ],
          "description": "International Freeform addresses - only valid for new addresses"
        },
        "foreign2": {
          "maxLength": 37,
          "type": [
            "string",
            "null"
          ],
          "description": "International Freeform addresses - only valid for new addresses"
        },
        "foreign3": {
          "maxLength": 59,
          "type": [
            "string",
            "null"
          ],
          "description": "International Freeform addresses - only valid for new addresses"
        },
        "suiteLinkIndicator": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "SuiteLink Indicator - Flag to indicate if we matched in SuiteLink."
        },
        "LACSLinkIndicator": {
          "maxLength": 1,
          "type": [
            "string",
            "null"
          ],
          "description": "LACSLink Indicator - Y/N flag to indicate whether a match is made in LACSLink®."
        },
        "LACSLinkReturnCode": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "LACSLink Return Code - Flag to indicate if we matched in LACSLink."
        },
        "postOfficeCity": {
          "type": "string",
          "maxLength": 50,
          "minLength": 0,
          "description": "The city associated with the delivery post office."
        },
        "postOfficeState": {
          "type": "string",
          "maxLength": 2,
          "minLength": 0,
          "description": "The state associated with the delivery post office."
        },
        "countyNumber": {
          "type": "string",
          "description": "The county number for the address."
        },
        "autoZoneIndicator": {
          "type": "string",
          "description": "The automated zone indicator for the delivery unit. * `A` - Carrier Route Sort Rates Apply - Merge Allowed. * `B` - Carrier Route Sort Rates Apply - Merge Not Allowed. * `C` - Carrier Route Sort Rates Do Not Apply - Merge Allowed. * `D` - Carrier Route Sort Rates Do Not Apply - Merge Not Allowed.",
          "enum": [
            "A",
            "B",
            "C",
            "D"
          ]
        },
        "miscLine": {
          "type": "string",
          "description": "Extraneous information removed from the address line not used to match the address."
        },
        "ZIP5Valid": {
          "type": "string",
          "description": "Indicates if the returned ZIP Code corresponds to the returned City/State. * `Y` - The ZIP Code matches the City/State. * `N` - The ZIP Code doesn't match the City/State.",
          "enum": [
            "Y",
            "N"
          ]
        },
        "POBoxOnlyZIP": {
          "type": "string",
          "description": "Indicates if the returned ZIP Code only serves PO Box addresses. * `Y` - The ZIP Code only serves PO Box addresses. * `N` - The ZIP Code serves non-PO Box addresses.",
          "enum": [
            "Y",
            "N"
          ]
        },
        "defaultFlag": {
          "type": "string",
          "description": "Indicates the address matched is a default. * `Y` - The address matched is a default. * `N` - The address matched is not a default.",
          "enum": [
            "Y",
            "N"
          ]
        },
        "matchedPrimaryNumber": {
          "type": "string",
          "description": "The value of the matched primary number."
        },
        "matchedSecondaryNumber": {
          "type": "string",
          "description": "The value of the matched secondary number."
        },
        "secondaryInfo": {
          "type": "string",
          "description": "The value of the secondary information."
        },
        "parsedPMBDesignator": {
          "type": "string",
          "description": "The value of the parsed PMB Designator."
        },
        "parsedPMBNumber": {
          "type": "string",
          "description": "The value of the PMB number."
        },
        "financeNumber": {
          "type": "string",
          "description": "Finance number associated with address."
        },
        "baseAlternateCode": {
          "type": "string",
          "description": "Base/Alternate code associated with ZIP + 4® record. * `A` - Alternate record. * `B` - Base record.",
          "enum": [
            "A",
            "B"
          ]
        },
        "eLOTCode": {
          "type": "string",
          "description": "eLOT Ascending/Descending Code * `A` - eLOT Number Ascending * `D` - eLOT Number Descending",
          "enum": [
            "A",
            "D"
          ]
        },
        "eLOTNumber": {
          "type": "string",
          "maxLength": 3,
          "minLength": 0,
          "description": "eLOT Number"
        },
        "electricVehicleRoute": {
          "type": [
            "string",
            "null"
          ],
          "description": "Electric Vehicle Route Indicator (Y/N)"
        }
      },
      "description": "The Address Information of the request user."
    },
    "DomesticAddress": {
      "title": "Domestic Address",
      "type": "object",
      "description": "Address fields for US locations",
      "properties": {
        "streetAddress": {
          "maxLength": 64,
          "type": [
            "string",
            "null"
          ],
          "description": "Primary and Secondary Address Information"
        },
        "streetAddressAbbreviation": {
          "maxLength": 50,
          "minLength": 0,
          "type": "string",
          "description": "This is the abbreviation of the primary 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)."
        },
        "lastline": {
          "maxLength": 42,
          "type": [
            "string",
            "null"
          ],
          "description": "Return/Standardized City State ZIP Code™"
        },
        "urbanization": {
          "$ref": "#/$defs/Urbanization"
        },
        "city": {
          "type": [
            "string",
            "null"
          ],
          "description": "City Name",
          "maxLength": 28
        },
        "cityAbbreviation": {
          "type": "string",
          "description": "This is the abbreviation of the city name for the address.",
          "maxLength": 28
        },
        "stateAbbr": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "State Abbreviation"
        },
        "ZIPCode": {
          "pattern": "^\\d{5}$",
          "type": [
            "string",
            "null"
          ],
          "description": "Return/Standardize ZIP Code™",
          "maxLength": 5
        },
        "ZIPPlus4": {
          "pattern": "^\\d{4}$",
          "type": [
            "string",
            "null"
          ],
          "description": "This is the 4-digit component of the ZIP+4 code.",
          "maxLength": 4
        },
        "deliveryPoint": {
          "maxLength": 2,
          "type": [
            "string",
            "null"
          ],
          "description": "Return/Standardize Delivery Point"
        }
      }
    },
    "Records": {
      "title": "Records",
      "description": "List of Records returned from found Old and New Address Information",
      "required": [
        "changeOfAddressInformation",
        "oldAddressInformation"
      ],
      "type": "object",
      "properties": {
        "changeOfAddressInformation": {
          "title": "Change Of Address",
          "type": "object",
          "properties": {
            "errorCode": {
              "maxLength": 3,
              "type": "string",
              "description": "Processing Error Code"
            },
            "errorDescription": {
              "maxLength": 255,
              "type": "string",
              "description": "Processing Error Description"
            },
            "beyondMonths": {
              "maxLength": 1,
              "type": "string",
              "description": "Change of address is beyond requested number of months. New address will not be returned.",
              "pattern": "^[YN]$"
            },
            "returnCode": {
              "maxLength": 2,
              "type": "string",
              "description": "NCOA Return Code - status of match to NCOA."
            },
            "moveEffectiveDate": {
              "type": "string",
              "format": "date",
              "description": "Change of address Move Effective Date: YYYY-MM-DD."
            },
            "moveType": {
              "type": "string",
              "enum": [
                "B",
                "F",
                "I"
              ],
              "description": "Indicates the type of move Business (B), Family (F) or Individual (I).",
              "pattern": "^[BFI]$"
            },
            "origFullName": {
              "maxLength": 66,
              "type": "string",
              "description": "Change of Address Original Full Name"
            },
            "matchedBusinessName": {
              "maxLength": 66,
              "type": "string",
              "description": "Returned result of the matched Business Name."
            },
            "matchedFirstName": {
              "maxLength": 15,
              "type": "string",
              "description": "Returned result of the matched First Name."
            },
            "matchedLastName": {
              "maxLength": 20,
              "type": "string",
              "description": "Returned result of the matched Last Name."
            },
            "matchedSuffixName": {
              "maxLength": 6,
              "type": "string",
              "description": "Returned result of the matched Suffix Name."
            },
            "middleNameTwoChars": {
              "maxLength": 2,
              "type": "string",
              "description": "Returned result of the matched Middle Name,"
            }
          },
          "description": "Information pertaining to the Change of address"
        },
        "oldAddressInformation": {
          "$ref": "#/$defs/AddressObject"
        },
        "newAddressInformation": {
          "$ref": "#/$defs/AddressObject"
        }
      }
    },
    "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)"
    }
  }
}