---
updatedAt: 2025-10-16T22:00:43.000Z
agentTools:
projectIndex: https://apidocs.ceretax.net/llms.txt
---
# Validate multiple addresses
This endpoint is intended for validating one or more US addresses for tax calculation purposes. It will attempt to standardize the submitted addresses and return location details for each address, including latitude and longitude coordinates.
Each address submitted must include one of the following field combinations:
* addressline1 + postalCode
* addressline1 + city + state
* freeform Address
Note: There is a max limit of 100 addresses to be validated at one time
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"x-stoplight": {
"id": "jqqefkafccjap"
},
"info": {
"title": "Address Validation API",
"description": "CereTax API Documentation for address validation.",
"version": "1.0"
},
"servers": [
{
"url": "https://av.cert.ceretax.net",
"description": "CERT"
},
{
"description": "Production",
"url": "https://av.prod.ceretax.net"
}
],
"paths": {
"/validate": {
"post": {
"tags": [
"Validate addresses"
],
"summary": "Validate multiple addresses",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/addressRequest"
},
"examples": {
"Address Validation Example": {
"value": [
{
"addressLine1": "3440 Preston Ridge #430",
"city": "Alpharetta",
"state": "GA",
"postalCode": "30005",
"country": "US"
}
]
},
"Freeform Address Validation Example": {
"value": [
{
"freeFormAddress": "ceretax 3440 preston ridge lane atlanta GA 30005"
}
]
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/addressResponse"
}
},
"examples": {
"Address Validation Response": {
"value": {
"results": [
{
"submittedAddressDetails": {
"addressLine1": "3440 Preston Ridge #430",
"addressLine2": "",
"city": "Alpharetta",
"state": "GA",
"postalCode": "30005",
"plus4": "",
"country": "US"
},
"validatedAddressDetails": {
"addressLine1": "3440 PRESTON RIDGE RD STE 430",
"addressLine2": "",
"city": "ALPHARETTA",
"state": "GA",
"postalCode": "30005",
"plus4": "3817",
"country": "US",
"fullAddress": "3440 PRESTON RIDGE RD # 430 ALPHARETTA GA 30005-3817"
},
"location": {
"accuracyType": "Rooftop",
"latitude": "34.07198",
"longitude": "-84.26348",
"plusCode": "866Q3PCP+QJ"
}
}
]
}
},
"Address Validation Response with Metadata": {
"value": {
"results": [
{
"locationCode": "string",
"submittedAddressDetails": {
"addressLine1": "3440 Preston Ridge #430",
"addressLine2": "",
"city": "Alpharetta",
"state": "GA",
"postalCode": "30005",
"plus4": "",
"country": "US"
},
"validatedAddressDetails": {
"addressLine1": "3440 PRESTON RIDGE RD STE 430",
"addressLine2": "",
"city": "ALPHARETTA",
"state": "GA",
"postalCode": "30005",
"plus4": "3817",
"country": "US",
"fullAddress": "3440 PRESTON RIDGE RD # 430 ALPHARETTA GA 30005-3817"
},
"location": {
"accuracyType": "Rooftop",
"latitude": "34.07198",
"longitude": "-84.26348",
"plusCode": "866Q3PCP+QJ"
},
"metadata": {
"recordType": "P",
"zipType": "Standard",
"countyFips": "42043",
"countyName": "Dauphin",
"residentialDeliveryIndicator": "Residential",
"dpvCode": "Y",
"dpvFootnotes": "AA"
}
}
]
}
},
"Freeform Address Validation Response": {
"value": {
"results": [
{
"submittedAddressDetails": {
"addressLine1": "",
"addressLine2": "",
"city": "",
"state": "",
"postalCode": "",
"plus4": "",
"country": "",
"freeformAddress": "ceretax 3440 preston ridge lane atlanta GA 30005"
},
"validatedAddressDetails": {
"addressLine1": "3440 PRESTON RIDGE RD",
"addressLine2": "",
"city": "ALPHARETTA",
"county": "Fulton",
"state": "GA",
"postalCode": "30005",
"plus4": "3817",
"country": "",
"fullAddress": "3440 PRESTON RIDGE RD ALPHARETTA GA 30005-3817"
},
"location": {
"latitude": 34.0723,
"longitude": -84.263344,
"plusCode": "866Q3PCP+WM",
"accuracyType": "Rooftop"
}
}
]
}
}
}
}
}
}
},
"security": [
{
"api_key": []
}
],
"description": "This endpoint is intended for validating one or more US addresses for tax calculation purposes. It will attempt to standardize the submitted addresses and return location details for each address, including lattitude and longitude coordinates.\n\nEach address submitted must include one of the following field combinations:\n- addressline1 + postalCode\n- addressline1 + city + state\n- freeformAddress",
"parameters": [
{
"schema": {
"type": "string",
"enum": [
"metadata",
"alternatematch"
]
},
"in": "query",
"name": "include",
"description": "Specify additional data elements to include in the response. Separate multiple values using a comma. _Available value(s): metadata, alternatematch_"
}
]
},
"parameters": []
}
},
"components": {
"schemas": {
"addressRequest": {
"type": "array",
"x-examples": {
"example-1": [
{
"locationCode": "string",
"addressLine1": "3440 Preston Ridge #430\"",
"addressLine2": "string",
"city": "Alpharetta",
"state": "GA",
"postalCode": "30005",
"plus4": "string",
"country": "US"
}
]
},
"items": {
"type": "object",
"properties": {
"locationCode": {
"type": "string",
"description": "A unique customer-provided identifier for the location or address that validation is being requested for"
},
"addressLine1": {
"type": "string",
"description": "The street line of the address, including the apartment, suite, or office number (if applicable).",
"example": "3440 Preston Ridge #430"
},
"addressLine2": {
"type": "string"
},
"city": {
"type": "string",
"description": "City component of the address",
"example": "Alpharetta"
},
"state": {
"type": "string",
"description": "State component of the address",
"example": "GA"
},
"postalCode": {
"type": "string",
"description": "Postal code component of the address (US and Canada only)\n Canada postal code must be uppercase, ex: S7R 1B7",
"example": "30005"
},
"plus4": {
"type": "string",
"description": "Plus-four code for the postal code of the address (US only)"
},
"country": {
"type": "string",
"description": "Country component of the address",
"example": "US"
},
"freeformAddress": {
"type": "string",
"description": "Addresses that are not stored in a structured format or that have additional information, like company name, building names, etc. can be passed in the freeformAddress field. CereTax will attempt to parse and validate the address.",
"example": "ceretax 3440 preston ridge road, alpharetta, ga 30005"
}
},
"required": [
"addressLine1",
"city",
"state",
"postalCode"
]
}
},
"addressResponse": {
"title": "Address validation response",
"type": "object",
"x-examples": {
"Address Validation Response": {
"results": [
{
"submittedAddressDetails": {
"addressLine1": "3440 Preston Ridge #430",
"addressLine2": "",
"city": "Alpharetta",
"state": "GA",
"postalCode": "30005",
"plus4": "",
"country": "US"
},
"validatedAddressDetails": {
"addressLine1": "3440 PRESTON RIDGE RD STE 430",
"addressLine2": "",
"city": "ALPHARETTA",
"state": "GA",
"postalCode": "30005",
"plus4": "3817",
"country": "US",
"fullAddress": "3440 PRESTON RIDGE RD # 430 ALPHARETTA GA 30005-3817"
},
"location": {
"accuracyType": "Rooftop",
"latitude": "34.07198",
"longitude": "-84.26348",
"plusCode": "866Q3PCP+QJ"
}
}
]
},
"Address Validation Response with Metadata": {
"results": [
{
"locationCode": "string",
"submittedAddressDetails": {
"addressLine1": "3440 Preston Ridge #430",
"addressLine2": "",
"city": "Alpharetta",
"state": "GA",
"postalCode": "30005",
"plus4": "",
"country": "US"
},
"validatedAddressDetails": {
"addressLine1": "3440 PRESTON RIDGE RD STE 430",
"addressLine2": "",
"city": "ALPHARETTA",
"state": "GA",
"postalCode": "30005",
"plus4": "3817",
"country": "US",
"fullAddress": "3440 PRESTON RIDGE RD # 430 ALPHARETTA GA 30005-3817"
},
"location": {
"accuracyType": "Rooftop",
"latitude": "34.07198",
"longitude": "-84.26348",
"plusCode": "866Q3PCP+QJ"
},
"metadata": {
"recordType": "P",
"zipType": "Standard",
"countyFips": "42043",
"countyName": "Dauphin",
"residentialDeliveryIndicator": "Residential",
"dpvCode": "Y",
"dpvFootnotes": "AA"
}
}
]
}
},
"properties": {
"results": {
"type": "array",
"description": "",
"items": {
"type": "object",
"properties": {
"locationCode": {
"type": "string",
"description": "A unique customer-provided identifier for the location or address that validation is requested for"
},
"submittedAddressDetails": {
"type": "object",
"description": "The original address details submitted for validation.",
"properties": {
"addressLine1": {
"type": "string",
"description": "The street line of the address, including the apartment, suite, or office number (if applicable).",
"example": "3440 Preston Ridge #430"
},
"addressLine2": {
"type": "string",
"description": "Any extra address information",
"example": ""
},
"city": {
"type": "string",
"description": "City component of the address",
"example": "Alpharetta"
},
"state": {
"type": "string",
"description": "State component of the address",
"example": "GA"
},
"postalCode": {
"type": "string",
"description": "Postal code component of the address (US and Canada only)\n Canada postal code must be uppercase, ex: S7R 1B7",
"example": "30005"
},
"plus4": {
"type": "string",
"description": "Plus-four code for the postal code of the address (US only)",
"example": ""
},
"country": {
"type": "string",
"description": "Country component of the address",
"example": "US"
},
"freeformAddress": {
"type": "string",
"description": "The freeform address passed in the API request (if applicable).",
"example": "ceretax 3440 preston ridge road, alpharetta, ga 30005"
}
}
},
"validatedAddressDetails": {
"type": "object",
"description": "The validated version of the submitted address.",
"properties": {
"addressLine1": {
"type": "string",
"description": "The street line of the address, including the apartment, suite, or office number (if applicable).",
"example": "3440 PRESTON RIDGE RD STE 430"
},
"addressLine2": {
"type": "string",
"description": "",
"example": ""
},
"city": {
"type": "string",
"description": "City component of the address",
"example": "ALPHARETTA"
},
"state": {
"type": "string",
"description": "State component of the address",
"example": "GA"
},
"postalCode": {
"type": "string",
"description": "Postal code component of the address (US and Canada only)\n Canada postal code will only validate the first 3 characters. We recommend you retain the 6 digit submitted postal code if you require the last 3 characters. We use lat/long for the tax calculation.",
"example": "30005"
},
"plus4": {
"type": "string",
"description": "Plus-four code for the postal code of the address (US only)",
"example": "3817"
},
"country": {
"type": "string",
"description": "Country component of the address",
"example": "US"
},
"fullAddress": {
"type": "string",
"description": "The fullly formatted address.",
"example": "3440 PRESTON RIDGE RD # 430 ALPHARETTA GA 30005-3817"
}
}
},
"location": {
"type": "object",
"description": "The physical location details of the validated address. The latitude, longitude, and plusCode values can be used in CereTax transaction requests to determine the appropriate taxing jurisdictions.",
"properties": {
"accuracyType": {
"type": "string",
"description": "The precision of the latitude and longitude values.",
"example": "Rooftop"
},
"latitude": {
"type": "number",
"description": "Geospatial latitude measurement of the address",
"example": "34.07198"
},
"longitude": {
"type": "number",
"description": "Geospatial longitude measurement of the address",
"example": "-84.26348"
},
"plusCode": {
"type": "string",
"description": "The Google Plus Code associated with the address",
"example": "866Q3PCP+QJ"
}
}
},
"metadata": {
"type": "object",
"description": "An optional object that can be included in the response when include=metadata is passed in the request url. The metadata object provides additional detail about the validated address.",
"properties": {
"recordType": {
"type": "string",
"description": "Indicates the type of match that was made for the address.\n- F: Firm; the finest level of match available for anaddress.\n- G: General Delivery; for mail to be held at local post offices.\n- H: High-rise; address contains apartment or building sub-units.\n- P: Post Office box\n- R: Rural Route or Highway Contract; may have box number ranges.\n- S: Street; address contains a valid primary number range.",
"example": "P"
},
"zipType": {
"type": "string",
"description": "Indicates the type of the ZIP Code for the address that was matched. Only given if a 5-digit match is made. (US Only)\n- Unique: The ZIP Code consists of a single delivery point, pertaining to a US Postal Service customer (like a large business or government agency) that routes all of its own mail internally.\n- Military: The ZIP Code pertains to military units and diplomatic organizations, often in foreign locations.\n- POBox: The ZIP Code is a PO Box ZIP Code and is assigned to a collection of Post Office Boxes.\n- Standard: The ZIP Code does not pertain to any of the above categories.",
"example": "Standard"
},
"countyFips": {
"type": "string",
"description": "The 5-digit county FIPS (Federal Information Processing Standards) code. It is a combination of a 2-digit state FIPS code and a 3-digit county code assigned by the NIST (National Institute of Standards and Technology). (US Only)",
"example": "42043"
},
"countyName": {
"type": "string",
"description": "The name of the county in which the address is located.",
"example": "Dauphin"
},
"residentialDeliveryIndicator": {
"type": "string",
"description": "Indicates whether an address is classified as residential or commercial.\n- Residential: The address is a residential address.\n- Commercial: The address is a commercial address.",
"example": "Residential"
},
"dpvCode": {
"type": "string",
"description": "Status of the Delivery Point Validation (DPV). This indicates whether or not the address is present in the USPS data.(US Only, no codes available for Canada)\n- Y: The Entire address is present in the USPS data.\n- N: The address is not present in the USPS data.\n- S: The main address is present in the USPS data, but the submitted secondary information (apartment, suite, etc.) was not recognized.\n- D: The main address is present in the USPS data, but it is missing secondary information (apartment, suite, etc.).",
"example": "Y"
},
"dpvFootnotes": {
"type": "string",
"description": "Information related to the delivery point validation of this address. All these footnotes have a length of 2 characters, and there may be up to 14 footnotes. Applies to US addresses only. No footnotes available for Canada.\n- AA : Street address, city, state, and ZIP are all valid.\n (e.g., 2335 S State St Ste 300 Provo UT)\n- A1 : Address is invalid.\n (e.g., 3214 N University Ave New York NY)\n- BB : Entire address is valid.\n (e.g., 2335 S State St Ste 300 Provo UT)\n- CC : The submitted secondary information (apartment, suite, etc.) was not recognized.\n (e.g., 2335 S State St Ste 500 Provo UT)\n- F1 : Military or diplomatic address\n (e.g., Unit 2050 Box 4190 APO AP 96278)\n- G1 : General delivery address\n (e.g., General Delivery Provo UT 84601)\n- M1 : Primary number (e.g., house number) is missing.\n (e.g., N University Ave Provo UT)\n- M3 : Primary number (e.g., house number) is invalid.\n (e.g., 16 N University Ave Provo UT)\n- N1 : Address is missing secondary information (apartment, suite, etc.).\n (e.g., 2335 S State St Provo UT)\n- PB : PO Box street style address.\n (e.g., 555 S B B King Blvd Unit 1 Memphis TN 38103)\n- P1 : PO, RR, or HC box number is missing.\n (e.g., Dept 126 Denver CO 802910126)\n- P3 : PO, RR, or HC box number is invalid.\n (e.g., PO BOX 60780 FAIRBANKS AK 99706)\n- RR : Confirmed address with private mailbox (PMB) info.\n (e.g., 3214 N University Ave #409 Provo UT)\n- R1 : Confirmed address without private mailbox (PMB) info.\n (e.g., 3214 N University Ave Provo UT)\n- R7 : Confirmed as a valid address that doesn't currently receive US Postal Service street delivery.\n (e.g., 6D Cruz Bay St John VI 00830)\n- U1 : Address has a 'unique' ZIP Code.\n (e.g., 100 North Happy Street 12345)\n\n Here are some common combinations:\n- AABB - ZIP, state, city, street, and primary number match.\n- AAM1 - ZIP, state, city, and street match, but the primary number is missing.\n- AAM3 - ZIP, state, city, and street match, but the primary number is invalid.\n- AAN1 - ZIP, state, city, street, and primary number match, but there is secondary information such as apartment or suite that would be helpful.\n- AABBR1 - ZIP, state, city, street, and primary number match. Address confirmed without private mailbox (PMB) info.",
"example": "AA"
}
}
},
"errorMessages": {
"type": "array",
"description": "The errorMessages object will only be returned in the response if any errors are encountered in the request or while validating the address. See [Status and Error Codes](https://apidocs.ceretax.net/reference/status-and-error-codes) for a complete list of possible errors.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "2001",
"description": "A 4-digit numerical error code representing the specific type of error."
},
"type": {
"type": "string",
"example": "Input",
"description": "Specifies the type of error, ex. input, authentication, situs"
},
"message": {
"type": "string",
"example": "Missing Required Fields",
"description": "A short description of the error."
},
"summary": {
"type": "string",
"example": "One or more required fields was not included in your API request",
"description": "A more detailed description of the error. May include dpv codes for troubleshooting. See metadata for dpv codes."
},
"errors": {
"type": "array",
"description": "The specific fields or values that triggered the error (when applicable).",
"items": {
"type": "string",
"example": "city: Please provide a value for city"
}
}
}
}
}
}
}
}
}
}
},
"securitySchemes": {
"api_key": {
"type": "apiKey",
"name": "x-api-key",
"in": "header"
}
}
},
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true,
"samples-enabled": true
},
"x-extension-3": null
}
```