Run several checks in one session
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_KEYon your server only (test_sandbox,prod_live). See Get a test key. - Product codes in the instance call.
GlobalScreeningtakesidv,aml,eidv1,eidv2.CustomerIntelligencetakesbin,phv(phone),emv(email),adv(address) andipv(device and IP). Any other value inGlobalScreeningreturns400. - 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:
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:
- One instance, many codes.
POST /api/v1/instance/createtakesGlobalScreening(idv,aml,eidv1,eidv2) andCustomerIntelligence(bin,phv,emv,adv,ipv) in the same body. It returns oneCorrelationId. - 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 withx-api-keyand the samex-correlation-id. There is no single endpoint that runs the whole stack for you. - 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. - The calls are independent. Run them in parallel. One failing does not stop the others: handle each result on its own.
- Hosted identity verification uses the same instance: if the list includes
idv, thewebEnrolmentUrlopens the hosted capture page and you follow the identity verification guide exactly. The other checks are server calls that share theCorrelationId.
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.
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#
// 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#
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#
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#
// 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#
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#
- Turn each product's result into
allow,step_up,revieworblockusing the rule in its own guide. - A check that did not run (
ok: false) is neverallow. Choosereview(fail closed) orallowwith a flag (fail open) for each product and write it down. combinetakes the most severe outcome. Store the per-product results with theCorrelationIdas your audit record.- AML
incompleteis neverclear.
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 and AML 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
CorrelationIdis 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
incompleteis never treated as clear - [ ] Any stack that includes
idvfollows the identity verification guide for the capture and reads the result withdocument/result - [ ] Per-product results are stored against the
CorrelationIdas the audit record