ScreenlyyIDDocs
Docs › Guides

Add address verification to your app

View as Markdown

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:

Before you start#

  • API key: read it from the environment variable SCREENLYYID_API_KEY on your server only. Use a test_ key for the sandbox and a prod_ 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) in CustomerIntelligence. It returns a CorrelationId that you send as x-correlation-id on the product call, along with x-api-key. A product call can be accepted only once per correlation id: repeating it with the same id can return 409 duplicate_correlation_id. Create a new instance for each check (for example one per checkout or per sign-up).
Shell
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#

  1. Create the instance in your server code, right before the check. Keep the CorrelationId with your own record (the user, the order). Do this on the server.
  2. Call the endpoint POST /api/v1/global-address with x-api-key, x-correlation-id and a JSON body (next section). In a typical app this is the sign-up or form-submit handler, before you create the account.
  3. Read the response and apply the decision logic: the fields marked ★ are the ones to base a decision on.
  4. Act on the result: accept, ask the customer to correct their input, flag for review, or block. Store the CorrelationId and the outcome: it is your audit trail, and the same id shows the check in the dashboard.
  5. Handle failures (below) so a provider outage never breaks your flow.

Request and response#

Request#

JSON
{
  "Record": [
    {
      "RecordID": "1",
      "AddressLine1": "22382 Avenida Empresa",
      "Locality": "Rancho Santa Margarita",
      "AdministrativeArea": "CA",
      "PostalCode": "92688",
      "Country": "US"
    }
  ]
}
FieldTypeMeaningExample
RecordarrayThe addresses to check. The property is named Record (singular) in the API.[ {...} ]
Record[].RecordIDstringYour id for the address, returned in the result.1
Record[].AddressLine1 … AddressLine8stringFree-form address lines.22382 Avenida Empresa
Record[].LocalitystringCity or town.Rancho Santa Margarita
Record[].AdministrativeAreastringState or province.CA
Record[].PostalCodestringPostal or ZIP code.92688
Record[].CountrystringCountry code or name.US

Response#

JSON
{
  "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"
    }
  ]
}
FieldTypeMeaningExample
TransmissionResultsstringResult 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.
TotalRecordsstringNumber 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[].Resultsstring★ Comma-separated result codes. Base the decision on them.(codes)

★ = base your decision on this field.

Decision logic#

  1. TransmissionResults is not empty, or TotalRecords is 0 / Records is 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).
  2. 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.
  3. When you accept, store FormattedAddress and the split fields, not the raw input.
JAVASCRIPT
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#

StatusWhenBody
400A required field is missing or the body is not valid JSONA problem-details object: {"type": "...", "title": "One or more validation errors occurred.", "status": 400, "errors": {"<Field>": ["The <Field> field is required."]}}
401x-api-key is missing or malformed, or the product is not activated on the accountEmpty body with a WWW-Authenticate header
409The same x-correlation-id was already used for this product{"error": "duplicate_correlation_id", "message": "Duplicate correlation id received."}
500The 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.

JSON
{"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)#

JAVASCRIPT
// 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)#

PYTHON
# 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#

JAVASCRIPT
// 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.

InputExpected result
22382 Avenida Empresa, Rancho Santa Margarita CA 92688, USA 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, AUThe same shape for a non-US address.
an address that does not existExpect 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 CorrelationId is sent
  • [ ] The request uses Record (an array), each entry with a RecordID
  • [ ] An empty Records result asks the customer to check the address instead of failing silently
  • [ ] The standardised address is what is stored
  • [ ] A test call returns 200