Add address verification to your app
Summary#
Address verification checks a postal address against reference data for the country and returns the standardised, formatted address with result codes. Use it at sign-up, checkout or onboarding to catch mistyped or non-existent addresses and to store addresses in a consistent format.
When to use it / when not to#
Use it for:
- an address form at sign-up, checkout or onboarding
- you need a standard address format before you ship, mail or store it
Do not use it for:
- You want to prove a person lives at an address: that is Electronic identity verification.
- Address matching for a person in AML screening: AML screening.
Before you start#
- API key: read it from the environment variable
SCREENLYYID_API_KEYon your server only. Use atest_key for the sandbox and aprod_key for live. Never put it in browser or mobile code. See Get a test key. - Base URL:
https://api.screenlyyid.com. HTTPS only. - Activation and plan: The address verification product (
adv) must be activated on the account. - Start with the Instance API. Every flow starts with
POST /api/v1/instance/create, listing this product's code (adv) inCustomerIntelligence. It returns aCorrelationIdthat you send asx-correlation-idon the product call, along withx-api-key. A product call can be accepted only once per correlation id: repeating it with the same id can return409 duplicate_correlation_id. Create a new instance for each check (for example one per checkout or per sign-up).
curl --request POST --url 'https://api.screenlyyid.com/api/v1/instance/create' \
--header "x-api-key: $SCREENLYYID_API_KEY" --header 'Content-Type: application/json' \
--data '{"GlobalScreening": [], "CustomerIntelligence": ["adv"]}'
# { "CorrelationId": "...", "webEnrolmentUrl": "..." } (webEnrolmentUrl is only used by the hosted identity verification flow)Use it on its own or stacked#
This product can be called on its own (one instance with just adv, as above) or stacked with other products for the same customer: list several product codes in the one instance call and send the same CorrelationId on each product's call. See Run several checks in one session. Example pairing: phone + email + address at sign-up (CustomerIntelligence: ["phv", "emv", "adv"]) or address + phone + AML for a marketplace seller.
Document and selfie identity verification is not part of this product. It only goes through the Instance API and the hosted capture page: see Identity verification (mobile) and Identity verification (web). Do not use the direct identity verification endpoints.
Implementation steps#
- Create the instance in your server code, right before the check. Keep the
CorrelationIdwith your own record (the user, the order). Do this on the server. - Call the endpoint
POST /api/v1/global-addresswithx-api-key,x-correlation-idand a JSON body (next section). In a typical app this is the sign-up or form-submit handler, before you create the account. - Read the response and apply the decision logic: the fields marked ★ are the ones to base a decision on.
- Act on the result: accept, ask the customer to correct their input, flag for review, or block. Store the
CorrelationIdand the outcome: it is your audit trail, and the same id shows the check in the dashboard. - Handle failures (below) so a provider outage never breaks your flow.
Request and response#
Request#
{
"Record": [
{
"RecordID": "1",
"AddressLine1": "22382 Avenida Empresa",
"Locality": "Rancho Santa Margarita",
"AdministrativeArea": "CA",
"PostalCode": "92688",
"Country": "US"
}
]
}| Field | Type | Meaning | Example |
|---|---|---|---|
Record | array | The addresses to check. The property is named Record (singular) in the API. | [ {...} ] |
Record[].RecordID | string | Your id for the address, returned in the result. | 1 |
Record[].AddressLine1 … AddressLine8 | string | Free-form address lines. | 22382 Avenida Empresa |
Record[].Locality | string | City or town. | Rancho Santa Margarita |
Record[].AdministrativeArea | string | State or province. | CA |
Record[].PostalCode | string | Postal or ZIP code. | 92688 |
Record[].Country | string | Country code or name. | US |
Response#
{
"Version": "...",
"TransmissionReference": "<your CorrelationId>",
"TransmissionResults": "",
"TotalRecords": "1",
"Records": [
{
"RecordId": "1",
"Results": "<result codes>",
"FormattedAddress": "22382 Avenida Empresa, Rancho Santa Margarita, CA 92688",
"AddressLine1": "22382 Avenida Empresa",
"Locality": "Rancho Santa Margarita",
"AdministrativeArea": "CA",
"PostalCode": "92688",
"CountryName": "United States of America"
}
]
}| Field | Type | Meaning | Example |
|---|---|---|---|
TransmissionResults | string | Result codes for the whole request (empty when it succeeded). A value here means the request itself was rejected by the address provider and no records come back. | |
TotalRecords | string | Number of records returned: one per address in the request that could be processed. | 1 |
Records[] | array | ★ One entry per address checked: RecordId, Results (result codes), FormattedAddress, the address split into parts, Locality, AdministrativeArea, PostalCode, CountryName and more. | (see the API reference) |
Records[].Results | string | ★ Comma-separated result codes. Base the decision on them. | (codes) |
★ = base your decision on this field.
Decision logic#
TransmissionResultsis not empty, orTotalRecordsis0/Recordsis empty: treat the address as not verified. Ask the customer to check it, and do not block them if the whole request was rejected (that is a provider problem, not a bad address).- For each record read
Results(comma-separated result codes) and apply your own acceptance rule. The code meanings are listed in the address verification reference. - When you accept, store
FormattedAddressand the split fields, not the raw input.
function addressDecision(res) {
const rec = res.Records?.[0];
if (!rec) return { action: "review", reason: "no_match" };
// decide using rec.Results (result codes) according to the reference; store the standardised form
return { action: "accept", formatted: rec.FormattedAddress, parts: rec };
}Errors and limits#
| Status | When | Body |
|---|---|---|
400 | A required field is missing or the body is not valid JSON | A problem-details object: {"type": "...", "title": "One or more validation errors occurred.", "status": 400, "errors": {"<Field>": ["The <Field> field is required."]}} |
401 | x-api-key is missing or malformed, or the product is not activated on the account | Empty body with a WWW-Authenticate header |
409 | The same x-correlation-id was already used for this product | {"error": "duplicate_correlation_id", "message": "Duplicate correlation id received."} |
500 | The upstream data provider failed | {"error": "internal_error", "message": "An unexpected error occurred"} |
No rate limit is documented. Use a 15 second timeout, do not retry 4xx, retry a 500 or timeout at most once.
Batch#
POST /api/v1/batch-global-address: Check many addresses in one request: put several objects in Record.
{"Record": [{"RecordID": "1", "AddressLine1": "...", "Locality": "...", "AdministrativeArea": "...", "PostalCode": "...", "Country": "US"}, {"RecordID": "2", "AddressLine1": "...", "Country": "AU"}]}The ScreenlyyID API sets no maximum number of records in its code. Send modest chunks and match results to inputs with RecordID.
Code#
Minimal working server-side code. It creates the instance, makes the call with a timeout and throws on a non-2xx response with the status and error body attached. The key is read from SCREENLYYID_API_KEY.
JavaScript (Node 18+, fetch)#
// server only: this reads your API key. Node 18 or later, no dependencies.
const API = "https://api.screenlyyid.com";
const apiKey = process.env.SCREENLYYID_API_KEY; // test_ while building, prod_ in production
if (!apiKey) throw new Error("SCREENLYYID_API_KEY is not set");
// Step 1: one instance per check. It lists this product's code and returns the CorrelationId.
export async function createInstance() {
const r = await fetch(`${API}/api/v1/instance/create`, {
method: "POST",
headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
body: JSON.stringify({ GlobalScreening: [], CustomerIntelligence: ["adv"] }),
});
if (!r.ok) throw new Error(`instance/create failed (HTTP ${r.status})`);
const { CorrelationId } = await r.json(); // spelled exactly like this
return CorrelationId;
}
// Step 2: Address verification checks a postal address against reference data for the country and returns the standardised, formatted address with result codes
export async function verifyAddress(address) {
const correlationId = await createInstance();
const r = await fetch(`${API}/api/v1/global-address`, {
method: "POST",
headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" },
body: JSON.stringify({ Record: [{ RecordID: "1", ...address }] }),
signal: AbortSignal.timeout(15000),
});
if (!r.ok) {
const error = new Error(`/global-address failed (HTTP ${r.status})`);
error.status = r.status;
error.body = await r.json().catch(() => null);
throw error;
}
return { correlationId, result: await r.json() };
}Python (requests)#
# server only: this reads your API key. Python 3.9 or later, pip install requests
import os
import requests
API = "https://api.screenlyyid.com"
API_KEY = os.environ["SCREENLYYID_API_KEY"] # test_ while building, prod_ in production
def create_instance():
"""Step 1: one instance per check. It lists this product's code and returns the CorrelationId."""
r = requests.post(
f"{API}/api/v1/instance/create",
headers={"x-api-key": API_KEY},
json={"GlobalScreening": [], "CustomerIntelligence": ["adv"]},
timeout=15,
)
r.raise_for_status()
return r.json()["CorrelationId"] # spelled exactly like this
def verify_address(address):
"""Step 2: Address verification checks a postal address against reference data for the country and returns the standardised, formatted address with result codes"""
correlation_id = create_instance()
r = requests.post(
f"{API}/api/v1/global-address",
headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id},
json={"Record": [{"RecordID": "1", **address}]},
timeout=15,
)
r.raise_for_status() # a requests.HTTPError carries r.status_code and r.json() for the error body
return correlation_id, r.json()Next.js route handler#
// app/api/verifyAddress/route.js (Next.js App Router). The key is read on the server only.
import { verifyAddress } from "@/lib/screenlyyid";
export const dynamic = "force-dynamic";
export async function POST(request) {
const input = await request.json();
try {
const { result } = await verifyAddress(input);
return Response.json(result); // send the browser only what it needs, never the API key or the CorrelationId
} catch (e) {
// a provider outage or timeout must not break your own flow: decide fail-open or fail-closed here
return Response.json({ error: "check_unavailable", status: e.status ?? null }, { status: 502 });
}
}Test it#
The sandbox runs real checks, so there are no special test addresses: use real addresses. A response with a non-empty TransmissionResults and no records means the request was rejected by the address provider, not that the address is bad.
| Input | Expected result |
|---|---|
| 22382 Avenida Empresa, Rancho Santa Margarita CA 92688, US | A complete, real address: expect TotalRecords 1 and a Records[0] with FormattedAddress, the address split into parts and Results codes. |
| 1 Martin Place, Sydney NSW 2000, AU | The same shape for a non-US address. |
| an address that does not exist | Expect Records[0].Results codes that show it was not verified, or no records. |
Done when#
- [ ] The API key is read only on the server
- [ ] A new instance is created per check and its
CorrelationIdis sent - [ ] The request uses
Record(an array), each entry with aRecordID - [ ] An empty
Recordsresult asks the customer to check the address instead of failing silently - [ ] The standardised address is what is stored
- [ ] A test call returns
200