Addrex documentation
Use Addrex in the console to clean spreadsheets, or connect through the validation API. These docs cover the current production workflow, Free Beta limits, downloads, API keys, responses, and error handling.
Spreadsheet upload
Prepare a CSV/XLS/XLSX file and clean it from the console.
Download results
Export standardized rows with status, confidence, ZIP+4, county, and source.
Validation API
Call the live validation endpoint with an API key.
Limits and errors
Understand Free Beta, paid quota, request IDs, and error bodies.
Spreadsheet workflow
Upload and clean a spreadsheet
The console upload workflow is the recommended path for beta users and non-technical users. It accepts CSV, XLS, and XLSX files, tracks processing, applies the account limit, and returns a downloadable CSV.
| Column names | Purpose |
|---|---|
| street, address, address_line, line1 | Street address. Required unless a single full-address column is used. |
| city | City name. Recommended for best match quality. |
| state | Two-letter state code or full state name. |
| zip, zipcode, postal_code | ZIP code. Optional but strongly recommended. |
| name, id, account_id | Optional customer fields. Keep these for joining the results back to your system. |
1. Open Uploads & Jobs. Go to the console and choose Uploads & Jobs.
2. Drop the file. Upload a CSV, XLS, or XLSX file up to the configured upload size limit.
3. Review status. The console shows progress, totals, and any Free Beta partial-processing message.
4. Download CSV. Download the completed file from the job result.
Results
Understand the downloaded CSV
Exports use a stable 17-column format so teams can review, filter, and import cleaned rows back into their own systems.
rowinput_streetinput_cityinput_stateinput_zipstd_streetstd_citystd_statestd_zipzip4carrier_routecountyfipsstatusconfidencedeliverabilitysourceVALIDATED, CORRECTED, NEEDS_REVIEW, and NOT_FOUND.D means deliverable, U means unknown or review needed, and N means not deliverable/not found.API
Validate one address from your application
Use an API key from the console. Send either one-line input or parsed address components. Responses include standardized fields, confidence, source, quality details, and usage headers.
| Method | Path | Description |
|---|---|---|
| GET or POST | /v1/validate | Validate one address. Accepts one-line input or parsed address components. |
| GET | /api/autocomplete/v1/suggest | Paid autocomplete suggestions. Not included in Free Beta. |
| GET | /api/autocomplete/v1/details | Details for a selected autocomplete suggestion. Not included in Free Beta. |
Use either Authorization: Bearer ADDREX_API_KEY or x-addrex-api-key: ADDREX_API_KEY.
Store keys server-side. Do not put API keys in browser code, mobile apps, screenshots, or public repositories.
The console may show only a key prefix after creation. Save the full key when it is generated.
One-line request
curl -X POST https://api.addrex.io/v1/validate \
-H "Authorization: Bearer ADDREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "447 French Hollow Rd Hardin IL 62047"
}'Component request
curl -X POST https://api.addrex.io/v1/validate \
-H "Authorization: Bearer ADDREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {
"line1": "447 French Hollow Rd",
"city": "Hardin",
"state": "IL",
"zip": "62047"
}
}'Example response
{
"id": "req_lx9h2m_ab12cd",
"status": "CORRECTED",
"validation_status": "CORRECTED",
"confidence": 0.95,
"input": {
"line1": "447 French Hollow Rd",
"city": "Hardin",
"state": "IL",
"zip": "62047"
},
"standardized": {
"line1": "447 FRENCH HOLLOW RD",
"city": "HARDIN",
"state": "IL",
"zip5": "62047",
"zip4": "1234",
"carrier_route": "R001",
"county": "CALHOUN",
"county_fips": "17013",
"deliverability": "D",
"source": "rust-engine"
},
"geocode": null,
"match_code": "ADDREX_ENGINE",
"match_source": "ADDREX_ENGINE",
"reason_codes": [],
"changes": [],
"quality": {
"match_strategy": "EXACT_VALIDATED",
"review_required": false,
"explanation": "Validated against reference data."
},
"latency_ms": 42
}Limits and errors
Plan limits, request IDs, and beta behavior
Every successful validation response includes usage headers when account context is available. Error responses are JSON and include a stable error code and message.
x-usage-used - lookups used in the current period.
x-usage-limit - included lookups for the current period.
x-usage-remaining - remaining included lookups.
x-request-id - support/debug identifier for the request.
400 bad_request - missing or malformed input.
401 unauthorized - missing or invalid token/key.
403 feature_unavailable - feature is not available on the plan.
429 quota_exceeded - Free Beta daily row allowance is exhausted.
402 lookup_limit_exceeded - production account has no remaining included lookups and overage is disabled.
Free Beta quota error
{
"error": "quota_exceeded",
"message": "You have used today's Free Beta row allowance. Processing resets tomorrow.",
"request_id": "req_lx9h2m_ab12cd",
"usage_summary": {
"used_today": 10000,
"daily_limit": 10000,
"remaining_today": 0,
"resets_at": "2026-05-30T00:00:00.000Z"
}
}Autocomplete
Autocomplete is not part of Free Beta
Paid accounts with autocomplete enabled can call the autocomplete routes. Free Beta users are blocked server-side and receive 403 feature_unavailable.
curl -G https://api.addrex.io/api/autocomplete/v1/suggest \
-H "Authorization: Bearer ADDREX_API_KEY" \
--data-urlencode "q=447 french" \
--data-urlencode "state=IL" \
--data-urlencode "limit=5" \
--data-urlencode "session_token=session_123"q - partial address query. Minimum length is enforced by the service.
limit - requested suggestion count, capped by the server.
state, zip, lat, lon - optional geographic hints.
session_token - recommended per user typing session for grouping usage.