ScreenlyyIDDocs
Docs › Guides

Run several checks in one session

View as Markdown

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 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, 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.
  • 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.
  • Start with the Instance API:
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": ["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, phone, email, address, device and IP, eIDV, 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 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:

OutcomeMeaning
allowEvery check passed.
step_upAsk for more: another document, an email confirmation, hosted identity verification.
reviewA person looks at it: AML potential_match, a card from another country, a MEDIUM identity result.
blockStop: invalid card or blocklisted IP, for example.

For identity verification, Decision.Level and the rest of the result are explained in 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#

StatusWhen
400instance/create with a code outside the lists above; a missing required field on a product call
401Missing or invalid key, or a product not activated on the account
409The same product was already called with this CorrelationId
429 / 402BIN daily cap / BIN allowance used; screening rate limit. See the BIN and AML guides
500 / 502The 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