Address validation API

1. Create an API key

Open API keys in the console after signing in. Keep your key on your server and provide it in the Authorization header. Do not include it in a browser bundle, URL, analytics event, or source repository.

The current API origin is https://api.addrex.dev. Use this HTTPS origin for the contract below.

curl --request POST 'https://api.addrex.dev/v1/validate' \
  --header "Authorization: Bearer $ADDREX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "street": "135 W Ravine Rd",
  "city": "Kingsport",
  "state": "TN",
  "zip": "37660",
  "include_quality": true
}'

This is an executable request example, not a promised result for this address. Actual output depends on the current reference data and matching evidence.

2. Request contract

POST /v1/validate accepts a JSON object. Use Content-Type: application/json. This endpoint does not accept the console adapter's input or nested address.line1 request shape. GET is not supported.

street

Required string. Include the house number, street name and any unit designator.

city

Optional string, default empty. Include the postal locality when known.

state

Optional string, default empty. Use the two-letter U.S. state abbreviation when known.

zip

Optional string, default empty. Preserve leading zeroes.

include_quality

Optional boolean, default true. Controls ax_quality_flags in the response.

For authentication, use Authorization: Bearer YOUR_API_KEY. The existing service also accepts x-api-key. It does not support an x-addrex-api-key alias.

3. Read the response

The response is one JSON object with the following fields. Optional evidence can be absent or empty. Preserve unknown status values so an integration can safely handle newly introduced categories.

status

Engine result category. May include VALID, CORRECTED, SUGGESTED, AMBIGUOUS, UNVERIFIED, NOT_FOUND and route-specific categories. A postal range match is not proof of a physical point or delivery.

ax_match_status

Compact match code: V valid, C corrected, S suggested/review, A ambiguous, U unverified, R rural route, P PO Box, X unresolved PO Box, N non-physical.

ax_quality_flags

Optional diagnostic flags; included when include_quality is true (the default). Treat as diagnostics, not a delivery guarantee.

ax_deliverability

Delivery evidence indicator. Interpret together with dpv and match_evidence; confidence or a ZIP+4 alone does not confirm a delivery point.

confidence

Numeric match confidence. It is not a measured probability of successful mail delivery.

input

Original components: street, city, state, zip.

result

Returned address components: street, city, state, zip. Optional nonempty zip4, carrier_route, county and fips. These fields are not guaranteed for every input.

match_evidence

Optional object: physical_point, postal_range, secondary, locality_valid, dpv and changed_components. Distinguishes physical evidence from postal range evidence.

dpv

Optional postal evidence: status, cmra, zip_plus4, carrier_route, delivery_point, footnote1, footnote2. Missing or empty values mean unavailable, not a negative confirmation.

dpv_lookup

Optional lookup acknowledgement: address_hash, acknowledged, found, dataset_version, hash_version. An acknowledged request does not mean a record was found.

source

Source identifier returned by the validation engine.

corrections

Array of changed component names, such as street, city, state or zip.

The legacy response described above does not return a canonical UUID, latitude/longitude, a standardized object, or a single-request latency_ms field. Additional resolution fields, when available, are described below. Address Intelligence in the website is a separate, evidence-based experience with its own availability checks.

Postal evidence and physical evidence

A ZIP+4 or postal range match does not establish that a specific building exists. A physical point match does not establish postal deliverability. DPV fields appear only when available; Addrex does not claim USPS CASS certification.

Resolution details, when available

Some responses may include an additional resolution object. Check for it before reading these fields; the current response can remain the legacy format above. The website, batch results and API use the returned address evidence. A missing resolution object does not imply an exact match.

submitted / matched

Submitted components and the selected canonical address, including its address_point_id and ZIP+4. matched is null when no unique complete address was selected.

result_class

VALIDATED, VALIDATED_WITH_CORRECTIONS, VALIDATED_UNIT_REQUIRED, NEAR_MATCH, AMBIGUOUS or NO_MATCH.

corrections / repair_level

Each component repair includes from, to and reason code. Levels 0–1 are exact or normalization; 2–3 explain repairs; 4 requires review.

confidence / scoring

Calibrated confidence can be null. The internal winning score, runner-up and margin are evidence scores, not probabilities.

dpv

Postal evidence attached to the selected canonical identity. Null remains unknown. It is separate from address match quality.

candidates

Review possible addresses for AMBIGUOUS and NEAR_MATCH. Never choose the first candidate automatically.

matched_primary / secondary_required

VALIDATED_UNIT_REQUIRED confirms only a primary address. Show the supplied secondary candidates and request a unit/building/floor. It does not select a unit UUID or borrow its DPV.

Repair example

This partial response illustrates explicit ZIP repair; it is not a promise of availability or a live lookup result.

{
  "result_class": "VALIDATED_WITH_CORRECTIONS",
  "repair_level": 2,
  "confidence": null,
  "corrections": [
    {
      "component": "zip",
      "from": "78640",
      "to": "78610",
      "code": "ZIP_CORRECTED"
    }
  ]
}

Review and secondary choice

For AMBIGUOUS, keep matched: null and show the candidate list. For VALIDATED_UNIT_REQUIRED, show matched_primary, secondary_candidate_count and the secondary choices; matched and dpv remain null. Submit the user's explicit completed address for a fresh result. Do not promote a candidate in browser code.

Authenticated batch requests

POST /v1/batch accepts { "addresses": [ { "street": "135 W Ravine Rd", "city": "Kingsport", "state": "TN", "zip": "37660", "include_quality": true } ] }. The implemented request cap is 10,000 addresses; this cap is not an account entitlement or throughput promise. Start with a small batch and check your account allowance. The response contains count, elapsed_ms, and results using the single-result fields above. An optional overage_warning: true indicates that the batch pre-check found the requested rows would exceed the current API usage allowance; that warning does not itself block the batch.

For a spreadsheet workflow, use Uploads & Jobs: select CSV, TXT/TSV or Excel, confirm the full-address or component columns, then process and download results. Downloads preserve submitted and matched fields, repairs, canonical identity, postal evidence, candidate lists and row errors when that evidence is returned. A failed or timed-out row is not a NO_MATCH result. The public first-address experience has no anonymous bulk interface.

Errors, limits and retries

401

Missing API key (api_key_required) or invalid credentials (invalid_credentials). Check the key and header without logging the secret.

400 / 415 / 422

Invalid batch size, content type, JSON or request fields. Correct the request before retrying. Framework error bodies can be text rather than JSON.

403 / 429

An edge or service access/rate limit can reject a request before validation. Observe Retry-After if supplied and avoid automatic retry loops.

5xx

Service or upstream failure. Retry with bounded backoff; a retry may count as another request. No idempotency guarantee is documented for this endpoint.

When available, x-addrex-usage, x-addrex-limit, and x-addrex-remaining report the API service's account usage. Optional x-addrex-overage and x-addrex-usage-warning provide additional context. These headers are best-effort and can lag a just-completed request.

Console Free Beta uses daily shared row usage. The external API currently uses its own account usage checks; do not treat console daily limits as an API entitlement. Review your account before running production volume. See current plans and service status information.

Availability

Data coverage and optional fields vary by location and input. Autocomplete access is separately controlled and is not included in the public demo. No throughput, latency, national completeness, or delivery guarantee is made by this reference.