United States Postal Service · Schema
Records Response
The Returned List of records
GovernmentPostal ServiceShippingLogisticsAddress ValidationPackage Tracking
Properties
| Name | Type | Description |
|---|---|---|
| numberOfMonths | integer | Number of months passed for for Change of Address |
| recordCount | integer | Number of Records in records Array returned to customer. |
| COABeyondMonthsCount | integer | Number of Records matched with a new address but outside requested number of Months. |
| COAMatchCount | integer | Number of Records returning a new address (within requested number of Months). |
| COANoMatchCount | integer | Number of Records with no COA found on file. |
| COAFoundCount | integer | Number of Records matched but no new address was available (e.g., MLNA, BCNO, new side wouldn't +4 code). |
| COANotAllowedMatchCount | integer | Number of Records returned for COA match not allowed (e.g., middle name mismatch, conflicting directions, etc). |
| records | array | Contains the records |
JSON Schema
{
"$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)"
}
}
}Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/usps-records-response"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.