API reference

Address validation API

Validate, standardize, and classify U.S. addresses from your own application. This reference covers the current production contract, authentication, request fields, response fields, limits, and errors.

Get API key Spreadsheet docs

Base URL

https://api.addrex.io

Auth

Bearer token or x-addrex-api-key header.

Free Beta

10,000 validation rows per day. Autocomplete excluded.

Endpoints

The validation endpoint is available to Free Beta and paid accounts. Autocomplete is available only for accounts with autocomplete enabled.

Method	Path	Auth	Status	Description
POST	/v1/validate	API key	Available	Validate one address from JSON input.
GET	/v1/validate	API key	Available	Validate one address from query parameters.
GET	/api/autocomplete/v1/suggest	API key	Paid plans	Return address suggestions for type-ahead UI. Not included in Free Beta.
GET	/api/autocomplete/v1/details	API key	Paid plans	Return details for a selected autocomplete suggestion. Not included in Free Beta.

POST request

curl -X POST https://api.addrex.io/v1/validate \
  -H "Authorization: Bearer ADDREX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "1361 rich lane buda texas 78610"
  }'

GET request

curl -G https://api.addrex.io/v1/validate \
  -H "Authorization: Bearer ADDREX_API_KEY" \
  --data-urlencode "input=1361 rich lane buda texas 78610"

Node.js

const response = await fetch("https://api.addrex.io/v1/validate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ADDREX_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    address: {
      line1: "1361 Rich Lane",
      city: "Buda",
      state: "TX",
      zip: "78610"
    }
  })
});

const result = await response.json();
console.log(result.status, result.standardized);

Python

import requests

response = requests.post(
    "https://api.addrex.io/v1/validate",
    headers={"Authorization": "Bearer ADDREX_API_KEY"},
    json={"input": "1361 rich lane buda texas 78610"},
    timeout=30,
)

print(response.status_code)
print(response.json())

Request body

Send either input or address.line1. City, state, and ZIP improve match quality.

Field	Type	Required	Description
input	string	No	One-line address. If provided, Addrex parses street, city, state, and ZIP.
address.line1	string	Yes*	Street address. Required when input is not provided.
address.line2	string	No	Apartment, suite, unit, or secondary address line.
address.city	string	No	City name. Recommended for higher confidence.
address.state	string	No	Two-letter state code or full state name.
address.zip	string	No	5-digit ZIP or ZIP+4. Recommended when available.

Response body

Responses are JSON. Successful responses use HTTP 200 and include normalized status, standardized address data, quality metadata, and latency.

Field	Type	Description
id	string	Request ID. Also returned in x-request-id header.
status	string	Product status: VALIDATED, CORRECTED, PARTIAL, or NOT_FOUND.
validation_status	string	Same normalized status as status for compatibility.
confidence	number	0.0 to 1.0 match confidence.
input	object	Normalized version of the submitted input.
standardized	object	Standardized address fields and delivery metadata.
standardized.line1	string	Standardized street line.
standardized.city	string	Standardized city.
standardized.state	string	Two-letter state code.
standardized.zip5	string	5-digit ZIP.
standardized.zip4	string	ZIP+4 when available.
standardized.carrier_route	string	Carrier route when available.
standardized.county	string	County name when available.
standardized.county_fips	string	County FIPS when available.
standardized.deliverability	string	D, U, or N when available.
match_code	string	Engine status/source code.
match_source	string	Source layer that produced the match.
reason_codes	string[]	Engine reason codes.
changes	string[]	Human-readable standardization changes.
quality	object	Reference quality and review guidance.
suggested_address	string	Optional reference suggestion when review is needed.
display_address	string	Optional display-friendly address.
latency_ms	number	End-to-end request latency measured by the API route.

Example response

{
  "id": "req_lx9h2m_ab12cd",
  "status": "CORRECTED",
  "validation_status": "CORRECTED",
  "confidence": 0.97,
  "input": {
    "line1": "1361 rich lane",
    "city": "buda",
    "state": "TX",
    "zip": "78610"
  },
  "standardized": {
    "line1": "1361 RICH LN",
    "city": "BUDA",
    "state": "TX",
    "zip5": "78610",
    "zip4": "1234",
    "carrier_route": "R001",
    "county": "HAYS",
    "county_fips": "48209",
    "deliverability": "D",
    "source": "rust-engine"
  },
  "geocode": null,
  "match_code": "ADDREX_ENGINE",
  "match_source": "ADDREX_ENGINE",
  "reason_codes": [],
  "changes": [
    "Street standardized from \"1361 rich lane\" to \"1361 RICH LN\""
  ],
  "latency_ms": 38
}

Usage headers

x-request-id

Support/debug ID for the request.

x-usage-used

Used lookups in the active period.

x-usage-limit

Included lookup allowance.

x-usage-remaining

Remaining included lookups.

Errors

Errors return JSON with error and message. Most validation errors also include request_id.

HTTP	Error	Meaning
400	bad_request	Missing address input or malformed request body.
401	unauthorized	Missing, invalid, inactive, or revoked API key.
402	lookup_limit_exceeded	Production account has no remaining included lookups and overage is disabled.
403	email_verification_required	Free Beta account must verify email before using validation.
403	feature_unavailable	Requested feature is not available on the current plan.
403	account_suspended	Account is suspended.
429	quota_exceeded	Free Beta daily row allowance is exhausted.
500	service_unavailable	Autocomplete service unavailable.
502	validation_failed	Validation engine request failed.

Production lookup limit

{
  "error": "lookup_limit_exceeded",
  "message": "No remaining lookup credits available. Upgrade your plan or enable overage processing.",
  "request_id": "req_lx9h2m_ab12cd",
  "limits": {
    "remainingLookupCredits": 0,
    "includedLookups": 2000,
    "usedLookups": 2000,
    "overageEnabled": false
  }
}

Free Beta autocomplete block

{
  "error": "feature_unavailable",
  "message": "Autocomplete is not included in the Free Beta program."
}

Beta and production behavior

Free Beta accounts can validate single addresses and process spreadsheet rows up to the daily allowance. Files larger than the remaining daily allowance process the allowed rows and report the unprocessed count. Paid production accounts use the plan's included lookup allowance; when overage is disabled, the API returns 402 before recording extra usage.

Key security

Keep API keys server-side.

Rotate keys if they are exposed.

Use request IDs when contacting support.