Real-Time Address Verification API: A Practical Guide

A real-time address verification API validates an address the moment you capture it, synchronously, in a single request, and hands back a structured answer your code can act on right away. That is the difference between real-time and the older batch model, where you upload a file, wait, and download the results later. For a signup form, a lead-intake webhook, or a checkout flow, batch is too slow. You need the answer while the user is still on the page or while the lead is still hot. This guide covers what real-time address verification means in practice, what a useful response looks like, and how to make your first call in curl, JavaScript, and Python.

Real-time versus batch, and why it matters

Batch verification is the right tool for periodic cleanup: take a list you already have, run it overnight, and write back the corrected addresses. Real-time verification is the right tool for the moment of capture. When a lead submits a form, you want to validate the address inside that same request, decide whether to accept it, and enrich it before it ever lands in your CRM. A real-time API is just a synchronous REST endpoint you call with one address and read a JSON response from, usually in well under a second.

The practical test is simple. If the result changes what happens next in the same user session or the same webhook, you need real-time. If it only feeds a report you look at later, batch is fine. Most teams end up running both: real-time at the edge of the funnel, and a batch pass for the back catalog.

What a real-time response should actually tell you

Plenty of APIs will confirm that an address is deliverable. That is necessary but it is not the whole job. Deliverability tells you the mail will arrive. It does not tell you whether the address is a house, what kind of property it is, or whether it is worth pursuing. A PO box and a warehouse are both perfectly deliverable, and both are useless if you are trying to reach homeowners.

A property-aware response answers the question you are really asking. In one call, AddressVerify returns whether the address is valid, the residential property type (one of seven classes), and an estimated home value. That lets you validate, classify, and score a lead in a single round trip. If you want the deeper story on the classification, see how to classify property type from an address and how to filter PO boxes and non-residential addresses.

Your first real-time call

The single-line endpoint takes a full address string and your API key in the x-api-key header. Here it is in curl:

curl -X POST 'https://api.addressverify.io/service/lookup/address' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "address": "20 Marie St, Iberia, MO 65486" }'

The response is a compact JSON object you can read in a couple of lines:

{
  "address": "20 Marie St, Iberia, MO 65486",
  "addressValid": true,
  "homeType": "SINGLE_FAMILY",
  "homeValue": 371000
}

Four fields, and you already know the address is real, it is a single-family home, and roughly what it is worth. The homeType is one of seven residential classes: SINGLE_FAMILY, TOWNHOUSE, CONDO, APARTMENT, MULTI_FAMILY, MANUFACTURED, or LOT, with UNKNOWN when the property cannot be resolved.

The same call in JavaScript and Python

Because it is a plain REST endpoint, the client is whatever you already use. In Node, the built-in fetch is enough:

const res = await fetch('https://api.addressverify.io/service/lookup/address', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ address: '20 Marie St, Iberia, MO 65486' }),
});

const data = await res.json();
if (data.addressValid && data.homeType === 'SINGLE_FAMILY') {
  // route the lead
}

And in Python with requests:

import requests

res = requests.post(
    "https://api.addressverify.io/service/lookup/address",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"address": "20 Marie St, Iberia, MO 65486"},
)

data = res.json()
if data["addressValid"] and data["homeType"] == "SINGLE_FAMILY":
    # route the lead
    pass

Multi-line addresses and expanded data

If your form already collects address components separately, post them to the fields endpoint instead of concatenating a string. It takes street, city, state, and zip:

curl -X POST 'https://api.addressverify.io/service/lookup/address/fields' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "street": "20 Marie St", "city": "Iberia", "state": "MO", "zip": "65486" }'

When you need more than type and value, add ?expanded=true to either endpoint. The response then includes an address breakdown, property details, tax assessment, and listing history, in the same call and at no extra cost:

{
  "address": "20 Marie St, Iberia, MO 65486",
  "addressValid": true,
  "homeType": "SINGLE_FAMILY",
  "homeValue": 371000,
  "propertyInfo": {
    "bedrooms": 4,
    "bathrooms": 2,
    "livingArea": 2072,
    "yearBuilt": 2001,
    "lotSize": "1.84 acres"
  },
  "taxAssessment": { "taxAssessedValue": 150210, "taxAssessmentYear": "2024" },
  "listing": { "lastSoldDate": "2025-05-22", "listingStatus": "recentlySold" }
}

Handling errors and rate limits in real time

Because the call sits in your request path, plan for the unhappy cases instead of assuming a clean 200. The status codes you will actually see are 400 for a malformed request, 401 for a bad API key, 402 when there is no active plan or balance, 422 for an address that cannot be parsed (usually a missing street number), and 429 when you exceed your rate limit.

• Set a timeout. A verification call should never block a form submission for more than a second or two. Wrap it with a timeout and decide up front what happens if it is exceeded.
• Degrade gracefully. If the call fails, do not drop the lead. Accept the submission, flag the address as unverified, and re-check it in a batch pass later.
• Respect 429. Back off and retry rather than hammering the endpoint. Check the calls-per-second your plan allows, not just the monthly total.
• Treat 422 as a signal, not a crash. An unparseable address is often a genuinely bad lead. Ask the user to correct it, or route it for review.

Where to call it in your funnel

The highest-value place to verify in real time is the point of capture. Validate on form submission so a bad address never enters your system clean. If you run inbound lead webhooks, verify inside the webhook handler and enrich the payload before it reaches your CRM. And if you gate expensive actions, a truck roll, a sales call, a direct-mail piece, put the check in front of that decision so you only spend on qualified, residential addresses.

The pattern is the same every time: one synchronous call, a structured response, and a branch in your code. Because the property type and value come back with the validation, you are not chaining three vendors to make a single decision. If you are moving off an older postal-only tool, the migration notes in USPS Web Tools API alternatives walk through the swap step by step.

Try it in a minute

The quickest way to see a real-time response is the free address verifier tool, which runs the same API against any address you paste in. When you are ready to integrate, the API documentation has the full endpoint reference and code in five languages, and pricing is pay-as-you-go with 50 free lookups a month, no credit card, so you can benchmark against your own list before you commit.