# Run several checks in one session

> Stack BIN, phone, email, address, IP, eIDV, AML and identity verification checks for one customer with a single Instance API call and one correlation id, then combine the results into one decision.

Canonical URL: https://www.screenlyyid.com/docs/guides/stacking-checks/

## Summary

Stacking means running several ScreenlyyID checks for the same customer under one `CorrelationId`: you create **one instance** that lists all the product codes, then make **one call per product** with that id. You get one audit trail in the dashboard and one place to combine the results. You make the combined decision in your own code from the per-product results.

## When to use it / when not to

- **Stack** when several checks belong to one customer journey and one decision: sign-up, checkout, client onboarding, a marketplace seller.
- **Use one product on its own** when you need a single check. It is the simplest: one instance with one code (each [product guide](https://www.screenlyyid.com/docs/guides/) shows it).
- Only the **direct identity verification endpoints** are reference only. Document and selfie identity verification goes through the Instance API and the hosted flow ([mobile](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/), [web](https://www.screenlyyid.com/docs/guides/identity-verification-web/)). Every other product (BIN, phone, email, address, device and IP, eIDV, AML screening) can be called on its own or stacked.

## Before you start

- **API key:** `SCREENLYYID_API_KEY` on your **server only** (`test_` sandbox, `prod_` live). See [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key).
- **Product codes** in the instance call. `GlobalScreening` takes `idv`, `aml`, `eidv1`, `eidv2`. `CustomerIntelligence` takes `bin`, `phv` (phone), `emv` (email), `adv` (address) and `ipv` (device and IP). Any other value in `GlobalScreening` returns `400`.
- **Activation:** each product must be activated on the account. A call for a product that is not activated returns `401`. Checks are billed per product: see the [pricing page](https://www.screenlyyid.com/pricing/).
- **Start with the Instance API:**

```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": ["aml"], "CustomerIntelligence": ["bin", "adv", "phv"]}'
# { "CorrelationId": "...", "webEnrolmentUrl": "..." }
```

## Use it on its own or stacked

This guide is the stacked case. For one product on its own, see its guide: [BIN](https://www.screenlyyid.com/docs/guides/bin-lookup/), [phone](https://www.screenlyyid.com/docs/guides/phone-validation/), [email](https://www.screenlyyid.com/docs/guides/email-validation/), [address](https://www.screenlyyid.com/docs/guides/address-verification/), [device and IP](https://www.screenlyyid.com/docs/guides/device-ip-intelligence/), [eIDV](https://www.screenlyyid.com/docs/guides/electronic-identity-verification/), [AML screening](https://www.screenlyyid.com/docs/guides/aml-screening/).

## Implementation steps

### How stacking works, exactly

This is what the API code does:

1. **One instance, many codes.** `POST /api/v1/instance/create` takes `GlobalScreening` (`idv`, `aml`, `eidv1`, `eidv2`) and `CustomerIntelligence` (`bin`, `phv`, `emv`, `adv`, `ipv`) in the same body. It returns one `CorrelationId`.
2. **Separate calls that share the id.** Each product is its own request to its own endpoint (`/bin-lookup`, `/phone-validate`, `/email-verify`, `/global-address`, `/ip-probe-verify`, `/eid-validate-1x1`, `/screening/person` ...), each sent with `x-api-key` and the same `x-correlation-id`. There is no single endpoint that runs the whole stack for you.
3. **Repeats can be refused.** A product call can be accepted only once per correlation id: a second BIN lookup with the same id returns `409 duplicate_correlation_id`. Create a new instance for the next customer or the next check rather than re-using an id.
4. **The calls are independent.** Run them in parallel. One failing does not stop the others: handle each result on its own.
5. **Hosted identity verification** uses the same instance: if the list includes `idv`, the `webEnrolmentUrl` opens the hosted capture page and you follow the [identity verification guide](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) exactly. The other checks are server calls that share the `CorrelationId`.

### How to get the combined outcome

There is **no combined result endpoint** for a stack. Each check returns its own result and you combine them. (`GET /api/v1/data/{sessionId}/decision/result` is part of the direct identity verification flow, keyed by a document `sessionId`: it is not a stack-wide result.) Read each product's decision logic in its own guide, turn each into one of four outcomes, and take the most severe:

| Outcome | Meaning |
|---|---|
| `allow` | Every check passed. |
| `step_up` | Ask for more: another document, an email confirmation, hosted identity verification. |
| `review` | A person looks at it: AML `potential_match`, a card from another country, a `MEDIUM` identity result. |
| `block` | Stop: invalid card or blocklisted IP, for example. |

For identity verification, `Decision.Level` and the rest of the result are explained in [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/).

```javascript
const SEVERITY = ["allow", "step_up", "review", "block"];
export const combine = (outcomes) =>
  outcomes.reduce((worst, o) => (SEVERITY.indexOf(o) > SEVERITY.indexOf(worst) ? o : worst), "allow");
```

### The stacking helper
```javascript
// server only. 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");

async function createInstance({ globalScreening = [], customerIntelligence = [] }) {
  const r = await fetch(`${API}/api/v1/instance/create`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify({ GlobalScreening: globalScreening, CustomerIntelligence: customerIntelligence }),
  });
  if (!r.ok) throw new Error(`instance/create failed (HTTP ${r.status})`);
  return r.json(); // { CorrelationId, webEnrolmentUrl }
}

// One product call. It never throws: a failure becomes { ok: false, status } so one outage cannot sink the stack.
async function check(correlationId, path, body) {
  try {
    const r = await fetch(`${API}/api/v1${path}`, {
      method: "POST",
      headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(15000),
    });
    return r.ok ? { ok: true, data: await r.json() } : { ok: false, status: r.status };
  } catch {
    return { ok: false, status: "timeout" };
  }
}

// One instance, several checks sharing its CorrelationId, run in parallel.
export async function runStack(products, calls) {
  const { CorrelationId, webEnrolmentUrl } = await createInstance(products);
  const entries = await Promise.all(
    Object.entries(calls).map(async ([name, [path, body]]) => [name, await check(CorrelationId, path, body)])
  );
  return { correlationId: CorrelationId, webEnrolmentUrl, results: Object.fromEntries(entries) };
}

// A check that could not run is "review", not "allow": decide your own fail-open or fail-closed rule here.
export const unavailable = (r) => !r.ok;
```

### Ready-made stacks

Each stack below uses `runStack`, then applies each product's decision rule (see its guide) and `combine`.

#### Sign-up: email + phone + IP/device
```javascript
export async function signupChecks({ email, phone, countryCode, ip, userAgent }) {
  const { correlationId, results } = await runStack(
    { customerIntelligence: ["emv", "phv", "ipv"] },
    {
      email: ["/email-verify", { Email: email, FixTypos: true }],
      phone: ["/phone-validate", { PhoneNumber: phone, CountryCode: countryCode }],
      ip: ["/ip-probe-verify", { IpAdress: ip }],
      blocklist: ["/ip-blocklist-verify", { IpAdress: ip, VPNLookup: true }],
      ua: ["/ua-lookup-verify", { UserAgent: userAgent }],
    }
  );
  const outcomes = [];
  const { email: e, phone: p, ip: i, blocklist: b } = results;
  if (unavailable(e) || unavailable(p)) outcomes.push("review");
  else {
    if (e.data.SyntaxError || e.data.DomainError || !e.data.Valid || e.data.IsDisposable) outcomes.push("block");
    if (!p.data.Valid) outcomes.push("block");
  }
  if (b.ok && (b.data.IsListed || b.data.IsTor || b.data.IsBot || b.data.IsMalware)) outcomes.push("block");
  if (i.ok && (i.data.IsVpn || i.data.IsProxy || i.data.IsHosting)) outcomes.push("review");
  return { correlationId, outcome: combine(outcomes), results };
}
```

#### Checkout: BIN + IP + email
```javascript
export async function checkoutChecks({ binNumber, billingCountry, ip, email }) {
  const { correlationId, results } = await runStack(
    { customerIntelligence: ["bin", "ipv", "emv"] },
    {
      bin: ["/bin-lookup", { BinNumber: binNumber, CustomerIpAddress: ip }],
      ip: ["/ip-blocklist-verify", { IpAdress: ip, VPNLookup: true }],
      email: ["/email-validate", { Email: email, FixTypos: true }],
    }
  );
  const outcomes = [];
  const { bin, ip: i, email: e } = results;
  if (unavailable(bin)) outcomes.push("review");
  else {
    if (!bin.data.Valid) outcomes.push("block");
    if (bin.data.IsPrepaid || bin.data.CountryCode !== billingCountry || !bin.data.IpMatchesBin) outcomes.push("review");
  }
  if (i.ok && (i.data.IsListed || i.data.IsTor || i.data.IsMalware)) outcomes.push("block");
  if (e.ok && (e.data.IsDisposable || !e.data.Valid)) outcomes.push("review");
  return { correlationId, outcome: combine(outcomes), results };
}
```

#### Tranche 2 client onboarding: hosted IDV + AML + eIDV
```javascript
// 1. Create the stacked instance and send the person to the hosted page (follow the identity verification guide exactly).
export async function startOnboarding() {
  const { CorrelationId, webEnrolmentUrl } = await createInstance({ globalScreening: ["idv", "aml", "eidv1"] });
  // save CorrelationId against the client; return webEnrolmentUrl to the app or page
  return { correlationId: CorrelationId, webEnrolmentUrl };
}

// 2. Server-side checks with the same CorrelationId (you can run these before or while the person captures their ID).
export async function onboardingChecks(correlationId, person) {
  const [aml, eidv] = await Promise.all([
    check(correlationId, "/screening/person", { GivenName: person.givenName, FamilyName: person.familyName, DateOfBirth: person.dob, Nationality: person.nationality }),
    check(correlationId, "/eid-validate-1x1", { Identity: { Completename: `${person.givenName} ${person.familyName}`, Dob: person.dob }, Address: person.address }),
  ]);
  const outcomes = [];
  if (!aml.ok || aml.data.outcome === "incomplete") outcomes.push("review");   // never treat incomplete as clear
  else if (aml.data.outcome === "potential_match") outcomes.push("review");
  if (!eidv.ok) outcomes.push("step_up");
  return { aml, eidv, outcome: combine(outcomes) };
}

// 3. After IDV_SESSION_COMPLETE, read the identity result once, with document/result (see the identity verification guide),
//    map Decision.Level HIGH/MEDIUM/LOW to allow/review/block, and combine it with the outcome above.
```

#### Marketplace seller: address + phone + AML
```javascript
export async function sellerChecks({ address, phone, countryCode, givenName, familyName, dob }) {
  const { correlationId, results } = await runStack(
    { globalScreening: ["aml"], customerIntelligence: ["adv", "phv"] },
    {
      address: ["/global-address", { Record: [{ RecordID: "1", ...address }] }],
      phone: ["/phone-validate", { PhoneNumber: phone, CountryCode: countryCode }],
      aml: ["/screening/person", { GivenName: givenName, FamilyName: familyName, DateOfBirth: dob }],
    }
  );
  const outcomes = [];
  const { address: a, phone: p, aml: m } = results;
  if (!m.ok || m.data.outcome !== "clear") outcomes.push("review");            // potential_match and incomplete both need a person
  if (!a.ok || !(a.data.Records && a.data.Records.length)) outcomes.push("step_up");
  if (!p.ok || !p.data.Valid) outcomes.push("step_up");
  return { correlationId, outcome: combine(outcomes), results };
}
```

## Request and response

The instance request and response are the same as in every guide (`GlobalScreening`, `CustomerIntelligence` in; `CorrelationId` and `webEnrolmentUrl` out). Each product call has its own request and response: see its guide. `runStack` returns `{ correlationId, webEnrolmentUrl, results }` where each entry of `results` is `{ ok: true, data }` or `{ ok: false, status }`.

## Decision logic

1. Turn each product's result into `allow`, `step_up`, `review` or `block` using the rule in its own guide.
2. A check that did not run (`ok: false`) is never `allow`. Choose `review` (fail closed) or `allow` with a flag (fail open) for each product and write it down.
3. `combine` takes the most severe outcome. Store the per-product results with the `CorrelationId` as your audit record.
4. AML `incomplete` is never `clear`.

## Errors and limits

| Status | When |
|---|---|
| `400` | `instance/create` with a code outside the lists above; a missing required field on a product call |
| `401` | Missing or invalid key, or a product not activated on the account |
| `409` | The same product was already called with this `CorrelationId` |
| `429` / `402` | BIN daily cap / BIN allowance used; screening rate limit. See the [BIN](https://www.screenlyyid.com/docs/guides/bin-lookup/) and [AML](https://www.screenlyyid.com/docs/guides/aml-screening/) guides |
| `500` / `502` | The upstream provider failed. Do not block the customer on it: apply your fail rule |

## Code

The code above is Node 18+ (fetch). The same pattern in Python is `requests.post` for the instance, then one `requests.post` per product with the same `x-correlation-id` header, run with `concurrent.futures.ThreadPoolExecutor`. In Next.js, call `signupChecks` or `checkoutChecks` from a route handler (`export async function POST(request)`), never from client code.

## Test it

Use a `test_` key. Each check is a separate call under one `CorrelationId`, and a check that fails comes back as `{ ok: false, status }` without stopping the others. To exercise the failure path, make one call fail on purpose (for example send a bad product body).

## Done when

- [ ] One instance lists every product used, and one `CorrelationId` is sent on every call for that customer
- [ ] Each product is called once per instance (a new instance for each new check), so no call returns `409`
- [ ] The API key is read only on the server
- [ ] A failed or timed-out check is handled by an explicit fail-open or fail-closed rule and never silently allowed
- [ ] Per-product outcomes are combined into one decision, and AML `incomplete` is never treated as clear
- [ ] Any stack that includes `idv` follows the identity verification guide for the capture and reads the result with `document/result`
- [ ] Per-product results are stored against the `CorrelationId` as the audit record

## Related

- [Guides index](https://www.screenlyyid.com/docs/guides/), [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/), [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/)
- [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/), [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/)
- [BIN lookup](https://www.screenlyyid.com/docs/guides/bin-lookup/), [Phone](https://www.screenlyyid.com/docs/guides/phone-validation/), [Email](https://www.screenlyyid.com/docs/guides/email-validation/), [Address](https://www.screenlyyid.com/docs/guides/address-verification/), [Device and IP](https://www.screenlyyid.com/docs/guides/device-ip-intelligence/), [eIDV](https://www.screenlyyid.com/docs/guides/electronic-identity-verification/), [AML screening](https://www.screenlyyid.com/docs/guides/aml-screening/)
