# Add address verification to your app

> Add address verification with ScreenlyyID: the instance call, the request, the response fields, the decision rule, working Node, Python and Next.js code, and a checklist.

Canonical URL: https://www.screenlyyid.com/docs/guides/address-verification/

## 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](https://www.screenlyyid.com/docs/guides/electronic-identity-verification/).
- Address matching for a person in AML screening: [AML screening](https://www.screenlyyid.com/docs/guides/aml-screening/).

## 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](https://www.screenlyyid.com/docs/ai-quickstart/#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).

```bash
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](https://www.screenlyyid.com/docs/guides/stacking-checks/). 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)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) and [Identity verification (web)](https://www.screenlyyid.com/docs/guides/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](https://www.screenlyyid.com/docs/guides/address-verification/#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"
    }
  ]
}
```

| 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
```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"
    }
  ]
}
```

| 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

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](https://www.screenlyyid.com/docs/api-reference/address-verification/).
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

| 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`.

```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.

| 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 `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`

## Related

- [Address verification (API reference)](https://www.screenlyyid.com/docs/api-reference/address-verification/)
- [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/)
- [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/)
