# ScreenlyyID developer documentation (full text) > ScreenlyyID (screenlyyid.com) is an identity verification, KYC and AML API. Everything a developer or coding agent needs to integrate ScreenlyyID. Each section begins with its canonical URL; every page is also available as Markdown at the same path plus `.md` (for example https://www.screenlyyid.com/docs/authentication.md). OpenAPI: https://www.screenlyyid.com/openapi.json. API base URL: https://api.screenlyyid.com. --- # ScreenlyyID developer documentation URL: https://www.screenlyyid.com/docs/ > Guides and API reference for integrating identity verification, AML screening and customer intelligence checks with ScreenlyyID. Canonical URL: https://www.screenlyyid.com/docs/ Integrate identity verification, AML screening and customer intelligence checks into your product with a single REST API, a mobile WebView integration, or no-code links. ScreenlyyID (screenlyyid.com) is an identity verification, KYC and AML API. Using a coding agent? Start with the [AI quickstart](https://www.screenlyyid.com/docs/ai-quickstart/).
AI quickstartThe prompt for your coding agent and the exact calls to add identity verification. RecipesWorking examples for Express, FastAPI, Next.js and iOS. Get startedCreate an account, choose your products and run your first check. AuthenticationAPI keys, session keys and the Instance API. Mobile app integrationHand document and selfie capture to ScreenlyyID from a WebView. API referenceEvery endpoint, with parameters, request bodies and code samples.
## Base URL and conventions All requests go to `https://api.screenlyyid.com` over HTTPS. Requests are JSON in, JSON out, and authenticated with an API key and a short-lived correlation ID. See [Authentication](https://www.screenlyyid.com/docs/authentication/). ## Where to go next - New to ScreenlyyID? Start with [Signing up](https://www.screenlyyid.com/docs/getting-started/signing-up/), then [Choose a product](https://www.screenlyyid.com/docs/getting-started/choose-a-product/). - Building the full onboarding flow? Read [How it works](https://www.screenlyyid.com/docs/getting-started/how-it-works/). - Reading results? See [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/). - Need working code? The [ScreenlyyID GitHub organisation](https://github.com/ScreenlyyID) has an iOS example and a JavaScript (Vue) SDK. --- # Integration guides URL: https://www.screenlyyid.com/docs/guides/ > One guide per ScreenlyyID product, written for developers and coding agents: pick what you want to do and follow the guide. Canonical URL: https://www.screenlyyid.com/docs/guides/ One self-contained guide per product. Each has the same sections (summary, when to use it, before you start, steps, request and response, decision logic, errors, code, test, a "Done when" checklist), so a coding agent can read one page and finish the integration. Every guide is also served as Markdown: add `.md` to its URL. ## I want to… | I want to… | Guide | |---|---| | Verify a user's ID document and selfie in my **mobile app** | [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) | | Verify a user's ID document and selfie in my **web app** | [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/) | | Check a card's country, type and prepaid status at checkout | [BIN lookup](https://www.screenlyyid.com/docs/guides/bin-lookup/) | | Validate phone numbers at sign-up | [Phone validation](https://www.screenlyyid.com/docs/guides/phone-validation/) | | Catch typos and fake or disposable emails, or verify a mailbox exists | [Email validation and verification](https://www.screenlyyid.com/docs/guides/email-validation/) | | Check and standardise postal addresses | [Address verification](https://www.screenlyyid.com/docs/guides/address-verification/) | | Spot VPNs, proxies, blocklisted IPs and device type | [Device and IP intelligence](https://www.screenlyyid.com/docs/guides/device-ip-intelligence/) | | Verify a person against data sources, without a document (1x1 or 2x2) | [Electronic identity verification](https://www.screenlyyid.com/docs/guides/electronic-identity-verification/) | | Screen a person or company against sanctions and PEP lists | [AML screening](https://www.screenlyyid.com/docs/guides/aml-screening/) | | Run several of these checks for one customer, with one decision | [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/) | ## How every guide starts Every flow starts with the [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) (`POST /api/v1/instance/create`), listing the product codes you need, and every later call sends your `x-api-key` and the returned `CorrelationId` as `x-correlation-id`. Product codes: `idv`, `aml`, `eidv1`, `eidv2` in `GlobalScreening`; `bin`, `phv`, `emv`, `adv`, `ipv` in `CustomerIntelligence`. Keep the API key on your server. ## Reference only The direct identity verification endpoints (enrolment, document, face, liveness, face match, `data/{sessionId}/...` and the document image endpoints) are **reference only. Do not integrate them.** Document and selfie identity verification always goes through the Instance API and the hosted flow in the two identity verification guides above. This applies only to those endpoints: BIN, phone, email, address, device and IP, eIDV and AML screening can each be used on their own or stacked. Using a coding agent? Give it the [AI quickstart](https://www.screenlyyid.com/docs/ai-quickstart/) prompt, or install the [agent skill](https://www.screenlyyid.com/docs/agent-skills/). --- # AI quickstart URL: https://www.screenlyyid.com/docs/ai-quickstart/ > Add ScreenlyyID identity verification to an app with a coding agent: a copy-paste prompt, the exact API calls, how to read the result, and how to go live. Canonical URL: https://www.screenlyyid.com/docs/ai-quickstart/ ScreenlyyID (screenlyyid.com) is an identity verification, KYC and AML API. You create a verification session from your server, send the person to a hosted page that captures their identity document and a selfie, then read the decision from your server. This page is written to be read by a coding agent (Claude Code, Cursor, Copilot, ChatGPT) as well as by a person. The same text is available as Markdown at [/docs/ai-quickstart.md](https://www.screenlyyid.com/docs/ai-quickstart.md), and every docs page is available as Markdown at its URL plus `.md`. ## Pick the right guide There is one guide per product, and the [guides index](https://www.screenlyyid.com/docs/guides/) has an "I want to..." table: | I want to... | Guide | |---|---| | Verify ID document and selfie in a mobile app | [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) | | Verify ID document and selfie in a web app | [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/) | | Check a card at checkout | [BIN lookup](https://www.screenlyyid.com/docs/guides/bin-lookup/) | | Validate phone numbers or emails at sign-up | [Phone](https://www.screenlyyid.com/docs/guides/phone-validation/), [Email](https://www.screenlyyid.com/docs/guides/email-validation/) | | Check addresses, IPs and devices | [Address](https://www.screenlyyid.com/docs/guides/address-verification/), [Device and IP](https://www.screenlyyid.com/docs/guides/device-ip-intelligence/) | | Verify a person without a document, or screen for sanctions | [eIDV](https://www.screenlyyid.com/docs/guides/electronic-identity-verification/), [AML screening](https://www.screenlyyid.com/docs/guides/aml-screening/) | | Run several checks for one customer | [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/) | Document and selfie identity verification only goes through the Instance API and the hosted flow. The direct identity verification endpoints in the API reference are reference only: do not integrate them. Every other product can be called on its own or stacked. ## Give this to your coding agent Copy this into your agent, then follow the one human step in [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key). ```text Read https://www.screenlyyid.com/llms.txt, pick the guide that matches what I asked for, read its .md version, and follow its steps and "Done when" checklist exactly. ScreenlyyID is an identity verification, KYC and AML API at screenlyyid.com (API base URL: https://api.screenlyyid.com, OpenAPI: https://www.screenlyyid.com/openapi.json). The guides' basics, if you need them first. To add identity verification: 1. Read the API key from the environment variable SCREENLYYID_API_KEY. Never put it in client-side code or commit it. 2. On the server, create a session with POST /api/v1/instance/create (headers: x-api-key, Content-Type: application/json; body: GlobalScreening ["idv"], CustomerIntelligence []). Save the CorrelationId against the user. Send the user to webEnrolmentUrl. 3. The hosted page sends the postMessage event IDV_SESSION_COMPLETE when the capture has been processed and the results are stored. When it arrives, from the server call GET /api/v1/document/result (and GET /api/v1/document/data) once, with the headers x-api-key and x-correlation-id. No polling is needed. Only if your app cannot receive the event (for example the person completes a link on another device) retry the call until it returns 200. 4. Store the decision for the user and gate the feature on it. 5. Add a test that mocks the three API calls, and handle 400 and 401 responses. Use a test_ key while building. Do not use a prod_ key. ``` ## Before you start - **Base URL:** `https://api.screenlyyid.com`. HTTPS only. - **Auth:** your API key in the `x-api-key` header on every request. - **Session token:** a `CorrelationId` that you get from the create-instance call and send in the `x-correlation-id` header on later calls for the same person. - **Product code:** the identity verification product is `idv`. A product has to be activated on your account before its code works. See [Authentication](https://www.screenlyyid.com/docs/authentication/#product-codes). - **Environment variable:** the examples on this page read the key from `SCREENLYYID_API_KEY`. That name is a convention for this guide. The API does not read environment variables, and there is no official SDK package to install: you call the REST API directly. ## Get a test key This is the one step an agent cannot do for you. 1. Register at [admin.screenlyyid.com/register](https://admin.screenlyyid.com/register) and choose the Free plan, then verify your email and complete your company details. See [Signing up](https://www.screenlyyid.com/docs/getting-started/signing-up/). 2. In the dashboard open **Integrations** and create an API key. Choose the test (sandbox) environment. Test keys start with `test_`; production keys start with `prod_`. 3. Put the key in your environment, for example in a `.env` file that is not committed: ```bash SCREENLYYID_API_KEY=test_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ``` ## 1. Create a verification session (server side) Call the [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/). ```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 '{ "FirstName": "Jane", "LastName": "Citizen", "GlobalScreening": ["idv"], "CustomerIntelligence": [] }' ``` A successful response is `200` with these two properties, spelled exactly like this: ```json { "CorrelationId": "6a0e5cb3-900c-41ca-ba84-08a08c6edff6", "webEnrolmentUrl": "https://app.screenlyyid.com/idv/6a0e5cb3-900c-41ca-ba84-08a08c6edff6" } ``` Store `CorrelationId` against your user. It is the session token for every later call. `FirstName`, `LastName` and `RedirectUrl` are optional. `ClientLookupId` is obsolete: do not send it. Node.js (version 18 or later, no dependencies): ```javascript // server only: never run this in the browser, it uses your API key export async function createVerification({ firstName, lastName }) { const response = await fetch("https://api.screenlyyid.com/api/v1/instance/create", { method: "POST", headers: { "x-api-key": process.env.SCREENLYYID_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ FirstName: firstName, LastName: lastName, GlobalScreening: ["idv"], CustomerIntelligence: [], }), }); if (!response.ok) throw new Error(`ScreenlyyID instance/create failed: HTTP ${response.status}`); const { CorrelationId, webEnrolmentUrl } = await response.json(); return { correlationId: CorrelationId, url: webEnrolmentUrl }; } ``` Python (requests): ```python import os import requests def create_verification(first_name, last_name): response = requests.post( "https://api.screenlyyid.com/api/v1/instance/create", headers={"x-api-key": os.environ["SCREENLYYID_API_KEY"], "Content-Type": "application/json"}, json={"FirstName": first_name, "LastName": last_name, "GlobalScreening": ["idv"], "CustomerIntelligence": []}, timeout=30, ) response.raise_for_status() body = response.json() return {"correlation_id": body["CorrelationId"], "url": body["webEnrolmentUrl"]} ``` ## 2. Send the person to the hosted flow Open `webEnrolmentUrl` in an iframe (see [Web app](https://www.screenlyyid.com/docs/integrations/web-app/)) or in a mobile WebView: the page reports its result to its parent window, so a page opened in its own tab or window cannot tell your app that it has finished. The page uses the camera, so ask for camera permission first: see [Camera permissions](https://www.screenlyyid.com/docs/integrations/mobile-app/#camera-permissions). ScreenlyyID captures the identity document, a selfie, face match and liveness. Add `?skipIntro=true` to go straight to capture. In a mobile WebView, listen for `postMessage` events. Events look like `{ "eventName": "", "isError": false, "error": "" }`: | Event | Meaning | |---|---| | `IDV_SESSION_COMPLETE` | The document and selfie have been collected. It is safe to close the WebView and continue your app. | | `ERROR` | A fatal error occurred while processing the images. `error` describes it. Restart the flow or continue your onboarding without verification. | See [Mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/) for the full WebView steps and the [iOS example app](https://github.com/ScreenlyyID/ios-sdk-example). ## 3. Get the result (server side) When the person has finished, call both endpoints from your server with the `x-api-key` and the `x-correlation-id` you stored. - [Get hosted SDK document data](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-document-data/): `GET /api/v1/document/data` returns the data read from the document (OCR and MRZ). - [Get hosted SDK decision result](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/): `GET /api/v1/document/result` returns the decision, with the document checks, liveness and face match. ```bash curl --request GET \ --url 'https://api.screenlyyid.com/api/v1/document/result' \ --header "x-api-key: $SCREENLYYID_API_KEY" \ --header "x-correlation-id: $CORRELATION_ID" ``` Node.js: ```javascript export async function getDecision(correlationId) { const response = await fetch("https://api.screenlyyid.com/api/v1/document/result", { headers: { "x-api-key": process.env.SCREENLYYID_API_KEY, "x-correlation-id": correlationId, }, }); if (!response.ok) return null; // only before IDV_SESSION_COMPLETE, or an error: see Errors return response.json(); } ``` Python: ```python import os import requests def get_decision(correlation_id): response = requests.get( "https://api.screenlyyid.com/api/v1/document/result", headers={"x-api-key": os.environ["SCREENLYYID_API_KEY"], "x-correlation-id": correlation_id}, timeout=30, ) return response.json() if response.ok else None ``` **Call once, after the event.** The hosted page sends `IDV_SESSION_COMPLETE` only after it has finished processing the document and selfie and the results are stored, so one call returns the result. You do not need to poll. If your app cannot receive the event (for example the person finishes a [no-code link](https://www.screenlyyid.com/docs/getting-started/integration-options/#no-code-links) on another device), call the result endpoint again every few seconds until you get a `200`. To understand the fields of the decision (trust factor scores, `Decision`, liveness and face match), read [Data retrieval](https://www.screenlyyid.com/docs/data/) and [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/). You can also see every verification in the dashboard under **Verifications**. ## Errors These are the responses the API returns. | Status | When | Body | |---|---|---| | `200` | Success | The result, or the session for create-instance. | | `400` | `instance/create`: a product code that does not exist or is not activated on your account | A problem-details JSON object: `{"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "traceId": "..."}`. It does not say which code was wrong, so check `GlobalScreening` and `CustomerIntelligence` first. | | `400` | The result endpoints without an `x-correlation-id` header | `{"error": "correlation_id_required", "message": "No correlation id found."}` | | `401` | `x-api-key` is missing or not valid | A problem-details object with `"title": "Unauthorized"` and `"status": 401`. Check that the key is complete, including its `test_` or `prod_` prefix. | | `500` | `GET /api/v1/document/result` or `/document/data` **before the capture has finished** (that is, before `IDV_SESSION_COMPLETE`), or for a `CorrelationId` that does not exist | `{"error": "internal_error", "message": "An unexpected error occurred"}`. If you only call after `IDV_SESSION_COMPLETE` you should not see this. If you do, contact ScreenlyyID support with the `CorrelationId`. | ## Test it - **Unit tests:** mock the create-instance and result calls, using the response shape shown above. Assert that your code sends `x-api-key` on the server and never in client code. - **End to end:** use a `test_` key, create a session, open `webEnrolmentUrl`, complete the capture, then call `GET /api/v1/document/result` with the stored `CorrelationId`. - **Debugging:** every request is listed under **Logs** in the dashboard, searchable by transaction ID. ## Go live 1. In the dashboard create a **production** key (Integrations, production environment). Production keys start with `prod_` and run real, billable checks. If the dashboard does not offer a production key yet, email [hello@screenlyyid.com](mailto:hello@screenlyyid.com). 2. Set `SCREENLYYID_API_KEY` to the production key in your production environment only. 3. Nothing else changes: the base URL is the same. ## More for agents - Working examples (Express, FastAPI, Next.js, iOS): [Recipes](https://www.screenlyyid.com/docs/recipes/) - Install the agent skill: [Agent skills](https://www.screenlyyid.com/docs/agent-skills/) - All developer docs as one Markdown file: [/docs/llms-full.txt](https://www.screenlyyid.com/docs/llms-full.txt) - OpenAPI spec: [/openapi.json](https://www.screenlyyid.com/openapi.json) - API catalog: [/.well-known/api-catalog](https://www.screenlyyid.com/.well-known/api-catalog) - Site index for language models: [/llms.txt](https://www.screenlyyid.com/llms.txt) --- # Agent skills URL: https://www.screenlyyid.com/docs/agent-skills/ > Install the ScreenlyyID agent skill so Claude Code, Cursor, Copilot and other coding agents can add identity verification to your app. Canonical URL: https://www.screenlyyid.com/docs/agent-skills/ The skills teach an AI coding agent to add ScreenlyyID checks to an app by following these docs. **`integrate-screenlyyid`** is the general entry point: it picks the right [guide](https://www.screenlyyid.com/docs/guides/), detects your stack and follows the matching [recipe](https://www.screenlyyid.com/docs/recipes/). There is also one skill per guide: `screenlyyid-idv-mobile`, `screenlyyid-idv-web`, `screenlyyid-bin-lookup`, `screenlyyid-phone-validation`, `screenlyyid-email-validation`, `screenlyyid-address-verification`, `screenlyyid-device-ip`, `screenlyyid-eidv`, `screenlyyid-aml-screening` and `screenlyyid-stacking-checks`. They are open source (MIT) at [github.com/ScreenlyyID/agent-skills](https://github.com/ScreenlyyID/agent-skills). The skill points at the documentation instead of copying it, so it stays correct as the docs change. For a one-off, you can instead paste the prompt from the [AI quickstart](https://www.screenlyyid.com/docs/ai-quickstart/). ## Install **Claude Code.** Copy the skill folder into your project (shared with your team) or into your user skills: ```bash git clone https://github.com/ScreenlyyID/agent-skills.git mkdir -p .claude/skills && cp -r agent-skills/screenlyyid-* agent-skills/integrate-screenlyyid .claude/skills/ ``` To use it in every project, copy it to `~/.claude/skills/` instead. Then ask: "Add ScreenlyyID identity verification to this app." **Other agents.** Most agents read an instructions file. Put the contents of the skill you need (the text of `integrate-screenlyyid` is below) where yours looks: - Cursor: `.cursor/rules/integrate-screenlyyid.mdc` - GitHub Copilot: `.github/copilot-instructions.md` - Agents that read `AGENTS.md`: add it there. - ChatGPT or any chat: paste it with your request. ## What you still do yourself Create a **test** API key: register at [admin.screenlyyid.com/register](https://admin.screenlyyid.com/register), open **Integrations** in the dashboard and create a key in the test environment (it starts with `test_`). An agent cannot sign up for you. Never give an agent a production key. See [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key). ## The skill This is the text of `integrate-screenlyyid/SKILL.md`. Each per-guide skill is short: it tells the agent to fetch and follow its guide. ScreenlyyID (screenlyyid.com) is an identity verification, KYC and AML API. Your server creates a verification session, the person is sent to a hosted page that captures their ID document and a selfie, and your server reads the result. ### Read these first - All developer docs in one file: https://www.screenlyyid.com/docs/llms-full.txt - The step-by-step guide for agents: https://www.screenlyyid.com/docs/ai-quickstart/ (Markdown: add `.md`, or send `Accept: text/markdown`) - One guide per product (pick the one that matches the request): https://www.screenlyyid.com/docs/guides/ (all guides are listed in https://www.screenlyyid.com/llms.txt) - Working examples: https://www.screenlyyid.com/docs/recipes/ - OpenAPI spec: https://www.screenlyyid.com/openapi.json Read the docs rather than guessing. Do not invent endpoints, packages, parameters or response fields. ### Rules 1. **The API key is server-only.** Read it from the environment variable `SCREENLYYID_API_KEY`. Never put it in browser code, a mobile app, a repository or a log. Every ScreenlyyID call is made by a server you control. 2. **There is no SDK package.** Do not run `npm install`, `pip install` or similar for a "screenlyyid" package: none exists. Use plain HTTP requests. 3. **Use a test key while building.** Test keys start with `test_`. You cannot create one: ask the user to register at https://admin.screenlyyid.com/register, open **Integrations** in the dashboard and create a key in the test environment. Never use a `prod_` key to develop or test. 4. **Spell names exactly.** `instance/create` returns `CorrelationId` (PascalCase) and `webEnrolmentUrl` (camelCase). 5. **Wait for the event, then read the result once.** The hosted page sends `IDV_SESSION_COMPLETE` when the capture has been processed and the results are stored. Do not poll before then and do not read the result from the browser or app. ### Steps #### 1. Pick the guide, then detect the stack Read https://www.screenlyyid.com/llms.txt, pick the guide that matches the request, read its `.md` version and follow its steps and its "Done when" checklist exactly. | The developer wants | Guide | |---|---| | Verify an ID document and selfie in a **mobile app** (iOS, Android, React Native, Flutter) | https://www.screenlyyid.com/docs/guides/identity-verification-mobile/ | | Verify an ID document and selfie in a **web app** | https://www.screenlyyid.com/docs/guides/identity-verification-web/ | | Card checks at checkout | https://www.screenlyyid.com/docs/guides/bin-lookup/ | | Phone, email, address, device or IP checks | https://www.screenlyyid.com/docs/guides/phone-validation/ , https://www.screenlyyid.com/docs/guides/email-validation/ , https://www.screenlyyid.com/docs/guides/address-verification/ , https://www.screenlyyid.com/docs/guides/device-ip-intelligence/ | | eIDV or AML screening | https://www.screenlyyid.com/docs/guides/electronic-identity-verification/ , https://www.screenlyyid.com/docs/guides/aml-screening/ | | Several checks for one customer | https://www.screenlyyid.com/docs/guides/stacking-checks/ | Then detect the stack and use the matching recipe for a complete working server: | Look for | Recipe | |---|---| | `express` in `package.json` | https://www.screenlyyid.com/docs/recipes/express/ | | `next` in `package.json` | https://www.screenlyyid.com/docs/recipes/nextjs/ | | `fastapi` in `requirements.txt` or `pyproject.toml` | https://www.screenlyyid.com/docs/recipes/fastapi/ | | An Xcode project (`*.xcodeproj`) | https://www.screenlyyid.com/docs/recipes/ios/ | | Any other server stack (Django, Flask, Rails, Go, Java, .NET, PHP, ...) | Translate the Express or FastAPI recipe: it is two HTTP calls. | Document and selfie identity verification only goes through the Instance API and the hosted flow. Never use the direct identity verification endpoints (enrolment, liveness, face match, `data/{sessionId}/...`): they are reference only. Every other product can be called on its own or stacked. #### 2. Get the key Check that `SCREENLYYID_API_KEY` is set to a `test_` key. If it is not, ask the user to create one (rule 3). Add the variable name to the project's `.env.example`, not the value. #### 3. Add two server routes - `POST /api/verifications`: call `POST https://api.screenlyyid.com/api/v1/instance/create` with the headers `x-api-key` and `Content-Type: application/json` and the body `{"GlobalScreening": ["idv"], "CustomerIntelligence": []}`. Store the returned `CorrelationId` against the signed-in user. Return only a verification id and `webEnrolmentUrl`, never the `CorrelationId`. - `GET /api/verifications/:id`: check the verification belongs to the signed-in user, then call `GET https://api.screenlyyid.com/api/v1/document/result` with the headers `x-api-key` and `x-correlation-id`. Return the outcome the app needs. If you also need the data read from the ID, call `GET /api/v1/document/data` the same way, and keep it on the server because it holds personal data. Use the user's existing authentication and database. Do not add a new framework for this. #### 4. Send the person to the hosted page - **Web:** embed `webEnrolmentUrl` in an iframe with `allow="camera; microphone"`, and listen for `message` events. Only accept a message whose `event.source` is that iframe's `contentWindow` and whose `event.origin` is the hosted page's origin. Messages look like `{ eventName, isError, error }`. On a desktop browser the page first shows a QR code to continue on a phone (same messages arrive when the phone finishes; add `handoff=off` to the URL to skip it). See https://www.screenlyyid.com/docs/integrations/web-app/ - **Mobile:** load `webEnrolmentUrl` in a WebView after the app has asked for camera permission, and forward the page's `message` events to the app. See https://www.screenlyyid.com/docs/integrations/mobile-app/ (including the camera permissions section). - `IDV_SESSION_COMPLETE` (with `isError` false): ask your server for the result. `ERROR`: the capture failed: offer to try again. #### 5. Test - Unit-test the two routes with the ScreenlyyID calls mocked. Assert that `x-api-key` is sent only from the server, that the `CorrelationId` is not in any response to the browser or app, and that another user's verification id returns 404. - With a `test_` key, create a verification and confirm the response has `CorrelationId` and `webEnrolmentUrl`. A real capture needs a camera and an ID document, so a person completes that step. #### 6. Go live Create a production key (`prod_`) in the dashboard, set `SCREENLYYID_API_KEY` to it in the production environment only, and change nothing else: the base URL is the same. If the dashboard does not offer a production key, ask the user to email hello@screenlyyid.com. ### Errors | Status | Meaning | |---|---| | 400 | `instance/create`: a product code that does not exist or is not activated on the account (problem-details body, it does not say which). On the result endpoints: no `x-correlation-id` header. | | 401 | Missing or invalid `x-api-key`. Check the key and its `test_` or `prod_` prefix. | | 500 `internal_error` | The result endpoints before the capture has finished, or for an unknown `CorrelationId`. If you only call after `IDV_SESSION_COMPLETE`, you should not see it. | Full table: https://www.screenlyyid.com/docs/ai-quickstart/#errors ### Do not - Do not call ScreenlyyID from the browser or a mobile app, or embed the key in them. - Do not commit keys, or print them in logs and error messages. - Do not invent SDKs, packages, endpoints or events. If the docs do not say it, ask. - Do not describe features that the docs do not describe. --- # Add identity verification to your mobile app URL: https://www.screenlyyid.com/docs/guides/identity-verification-mobile/ > Verify a person's ID document and selfie inside your iOS, Android, React Native or Flutter app with the Instance API and the hosted capture page in a WebView. Follow the four steps exactly. Canonical URL: https://www.screenlyyid.com/docs/guides/identity-verification-mobile/ > **Agent rules (must follow)** > > - MUST create the instance on your **server** with `POST /api/v1/instance/create`, and MUST store the `CorrelationId` against the user. > - MUST NOT put the API key in the app, and MUST NOT call the result APIs from the app. Only your back end calls `GET /api/v1/document/data` and `GET /api/v1/document/result`. > - MUST open the returned `webEnrolmentUrl` in a WebView, and MUST use the exact event names `IDV_SESSION_COMPLETE` and `ERROR` with the `{ eventName, isError, error }` format. > - MUST treat `ERROR` as a failure the user can restart. > - MUST NOT build a custom camera, upload, liveness or face-match flow. > - MUST NOT call the direct identity verification endpoints (enrolment, liveness, face match, `data/{sessionId}/...`), even if the developer asks. They are reference only. Identity verification always goes through the Instance API and the hosted `webEnrolmentUrl`. > - MUST NOT call the result endpoints before `IDV_SESSION_COMPLETE`, and MUST NOT poll. > - The canonical human page for this flow is [Mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/). If this guide and that page ever differ, tell the developer and follow that page. ## Summary The mobile integration hands document and selfie capture to ScreenlyyID from a WebView inside your app, so users never leave your app. Your server creates an instance, the app opens the hosted capture page, the page tells the app when it is finished, and your server reads the decision. It works on any mobile platform that has a WebView. ## When to use it / when not to **Use it for** verifying a person's identity document, face match and liveness inside a native or cross-platform mobile app. **Do not use it for:** - A web app: use [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/). - Checks that need no document or selfie (BIN, phone, email, address, IP, eIDV, AML): see the [guides index](https://www.screenlyyid.com/docs/guides/). ## Before you start - **API key:** `SCREENLYYID_API_KEY` on your **back end only**. `test_` for the sandbox, `prod_` for live. Never in the app. See [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key). - **Base URL:** `https://api.screenlyyid.com`. The capture page is served over HTTPS only (`https://app.screenlyyid.com`). - **Product:** `idv` goes in `GlobalScreening` in the instance call, and must be activated on the account. - **A back end you control.** Mobile apps cannot hold the key. The [iOS sample app](https://github.com/ScreenlyyID/ios-sdk-example) has a small `backend/` for this; so do the [Express](https://www.screenlyyid.com/docs/recipes/express/) and [FastAPI](https://www.screenlyyid.com/docs/recipes/fastapi/) recipes (the same two routes). - **A real device.** The camera does not work in the iOS simulator. ```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": ["idv"], "CustomerIntelligence": []}' # { "CorrelationId": "...", "webEnrolmentUrl": "https://app.screenlyyid.com/idv/..." } ``` ## Use it on its own or stacked Identity verification can run on its own (`GlobalScreening: ["idv"]`) or in the same instance as other checks for the same customer, for example `["idv", "aml", "eidv1"]` for client onboarding. The capture flow below does not change: the other checks are server calls that send the same `CorrelationId`. See [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/). Document and selfie identity verification only goes through the Instance API and the hosted flow. The direct identity verification endpoints are reference only. ## Implementation steps These are the four steps of the [Mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/) page, in the same order. ### Step 1: Create an instance (server) Call `POST /api/v1/instance/create` from your back end. Save the `CorrelationId` against the user. Send only a verification id and the `webEnrolmentUrl` to the app. The response is `200` and the property names are exactly `CorrelationId` and `webEnrolmentUrl`. ```javascript // back end route: POST /api/verifications (Node 18+) const r = await fetch("https://api.screenlyyid.com/api/v1/instance/create", { method: "POST", headers: { "x-api-key": process.env.SCREENLYYID_API_KEY, "Content-Type": "application/json" }, body: JSON.stringify({ GlobalScreening: ["idv"], CustomerIntelligence: [] }), }); if (!r.ok) throw new Error(`instance/create failed (HTTP ${r.status})`); const { CorrelationId, webEnrolmentUrl } = await r.json(); // save CorrelationId against the user; return { verificationId, webEnrolmentUrl } to the app ``` ### Step 2: Open the WebView (app) Ask for camera permission **before** loading the page, then load `webEnrolmentUrl` in a WebView. Add `?skipIntro=true` to skip the intro screen and go straight to capture. The page needs: JavaScript enabled, camera (and microphone) access, inline media playback, and HTTPS. ### Step 3: Listen for events (app) The hosted page sends its events with `window.parent.postMessage({ eventName, isError, error }, "*")`. Inside a WebView there is no outer page, so the event arrives as a `message` event **inside the page**. The page sends it only this way: it has no iOS-, Android-, React Native- or Flutter-specific call. `iosListener`, `AndroidListener` and `FlutterListener` are names your app registers for its own bridge, and `ReactNativeWebView` is the object that `react-native-webview` provides; the script you inject forwards each `message` event to it. Every platform therefore does the same two things: inject a small script that listens for `message` events, and pass each event to the app. The names in the platform sections below are the names the samples register. | Event | Meaning | What to do | |---|---|---| | `IDV_SESSION_COMPLETE` | The document and selfie have been processed and the results are stored. | Close the WebView and ask your back end for the result (Step 4). | | `ERROR` (`isError` is `true`) | A fatal error while processing the images. `error` describes it. | Offer to restart: create a new instance and open the new `webEnrolmentUrl`. | Act once: ignore further events after the first terminal event. ### Step 4: Get the result (back end) When the app reports `IDV_SESSION_COMPLETE`, it calls **your** back end, which calls both endpoints once with `x-api-key` and the stored `x-correlation-id`: ```javascript const headers = { "x-api-key": process.env.SCREENLYYID_API_KEY, "x-correlation-id": correlationId }; const [data, result] = await Promise.all([ fetch("https://api.screenlyyid.com/api/v1/document/data", { headers }).then((r) => r.json()), fetch("https://api.screenlyyid.com/api/v1/document/result", { headers }).then((r) => r.json()), ]); ``` The `500 internal_error` response means the capture has not finished: you called too early. If you only call after `IDV_SESSION_COMPLETE` you will not see it. ## Platform code All four platforms need the same things. Replace `webEnrolmentUrl` with the value from Step 1. ### iOS (Swift, WKWebView) From the [iOS sample app](https://github.com/ScreenlyyID/ios-sdk-example) (`DemoCamera/ViewController.swift`, `HomeViewController.swift`, `Info.plist`). `Info.plist`: `NSCameraUsageDescription` (and `NSMicrophoneUsageDescription`) with text that tells the user why. ```swift import AVFoundation import WebKit // Before loading the page: AVCaptureDevice.authorizationStatus(for: .video) // .notDetermined -> AVCaptureDevice.requestAccess(for: .video), load only if granted // .denied / .restricted -> do not load; explain and offer to open Settings class VerifyViewController: UIViewController, WKScriptMessageHandler { var webView: WKWebView! var url: URL! // the webEnrolmentUrl private var finished = false override func viewDidLoad() { super.viewDidLoad() let config = WKWebViewConfiguration() config.preferences.javaScriptEnabled = true config.allowsInlineMediaPlayback = true // the camera preview plays inside the page // forward the page's message events to the app let source = "window.addEventListener('message', function(e) { window.webkit.messageHandlers.iosListener.postMessage(JSON.stringify(e.data)) })" config.userContentController.addUserScript(WKUserScript(source: source, injectionTime: .atDocumentEnd, forMainFrameOnly: false)) config.userContentController.add(self, name: "iosListener") webView = WKWebView(frame: view.bounds, configuration: config) view.addSubview(webView) webView.load(URLRequest(url: url)) } func userContentController(_ c: WKUserContentController, didReceive message: WKScriptMessage) { guard !finished, let body = message.body as? String, let event = try? JSONSerialization.jsonObject(with: Data(body.utf8)) as? [String: Any], let name = event["eventName"] as? String else { return } let isError = (event["isError"] as? Bool) ?? false if name == "IDV_SESSION_COMPLETE" && !isError { finished = true // close the WebView, then ask YOUR back end for the result } else if name == "ERROR" { finished = true // show event["error"], offer to restart with a new instance } } } ``` ### Android (Kotlin, WebView) Manifest: `` (and `android.permission.INTERNET`). Request `CAMERA` at runtime before loading the page. ```kotlin import android.webkit.* class VerifyActivity : AppCompatActivity() { private lateinit var webView: WebView private var finished = false // exposed to the page's JavaScript as window.AndroidListener inner class Bridge { @JavascriptInterface fun onMessage(json: String) { runOnUiThread { if (finished) return@runOnUiThread val event = org.json.JSONObject(json) val isError = event.optBoolean("isError", false) when (event.optString("eventName")) { "IDV_SESSION_COMPLETE" -> if (!isError) { finished = true /* close, ask YOUR back end for the result */ } "ERROR" -> { finished = true /* show event.optString("error"), offer to restart */ } } } } } fun load(webEnrolmentUrl: String) { webView = findViewById(R.id.webview) webView.settings.javaScriptEnabled = true webView.settings.mediaPlaybackRequiresUserGesture = false webView.addJavascriptInterface(Bridge(), "AndroidListener") webView.webChromeClient = object : WebChromeClient() { override fun onPermissionRequest(request: PermissionRequest) { // grant the page's camera request once the app itself has the CAMERA permission runOnUiThread { request.grant(request.resources) } } } webView.webViewClient = object : WebViewClient() { override fun onPageFinished(view: WebView, url: String) { view.evaluateJavascript( "window.addEventListener('message', function(e) { AndroidListener.onMessage(JSON.stringify(e.data)) })", null) } } webView.loadUrl(webEnrolmentUrl) } } ``` ### React Native (react-native-webview) `npm install react-native-webview`. iOS: add `NSCameraUsageDescription` to `Info.plist`. Android: add the `CAMERA` permission to the manifest and request it with `PermissionsAndroid` before rendering the WebView. ```javascript import { WebView } from "react-native-webview"; const forwardMessages = ` window.addEventListener('message', function (e) { window.ReactNativeWebView.postMessage(JSON.stringify(e.data)); }); true; `; export function VerifyScreen({ webEnrolmentUrl, onComplete, onError }) { const done = React.useRef(false); return ( { if (done.current) return; const event = JSON.parse(e.nativeEvent.data); if (event.eventName === "IDV_SESSION_COMPLETE" && !event.isError) { done.current = true; onComplete(); } // then ask YOUR back end for the result else if (event.eventName === "ERROR") { done.current = true; onError(event.error); } // offer to restart }} /> ); } ``` ### Flutter (webview_flutter) `flutter pub add webview_flutter permission_handler`. iOS: `NSCameraUsageDescription` in `Info.plist`. Android: the `CAMERA` permission in the manifest. Request camera permission with `permission_handler` before creating the controller. ```dart import 'dart:convert'; import 'package:webview_flutter/webview_flutter.dart'; late final WebViewController controller; bool finished = false; void startVerification(String webEnrolmentUrl, void Function() onComplete, void Function(String) onError) { controller = WebViewController() ..setJavaScriptMode(JavaScriptMode.unrestricted) ..addJavaScriptChannel('FlutterListener', onMessageReceived: (JavaScriptMessage m) { if (finished) return; final event = jsonDecode(m.message) as Map; final isError = event['isError'] == true; if (event['eventName'] == 'IDV_SESSION_COMPLETE' && !isError) { finished = true; onComplete(); } // then ask YOUR back end for the result else if (event['eventName'] == 'ERROR') { finished = true; onError('${event['error']}'); } // offer to restart }) ..setNavigationDelegate(NavigationDelegate(onPageFinished: (_) { controller.runJavaScript( "window.addEventListener('message', function(e) { FlutterListener.postMessage(JSON.stringify(e.data)) })"); })) ..loadRequest(Uri.parse(webEnrolmentUrl)); } // Render it with WebViewWidget(controller: controller). // For inline camera on Android, grant the page's request with AndroidWebViewController.setOnPlatformPermissionRequest. ``` ## Reading the result `GET /api/v1/document/result` returns the decision. The fields to use (see [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/)): | Field | Type | Meaning | |---|---|---| | `Decision.Level` | string | ★ The overall confidence: `HIGH` (passed), `MEDIUM` (suspicious, additional checks recommended), `LOW` (not passed). | | `LivenessResult.Result` | string | ★ `Live` or `Not Live`. | | `FaceMatchResult.IsMatch` | boolean | ★ Whether the selfie matches the ID photo. | | `Verifications.*` | object | Each data point (`DateOfExpiration`, `DocumentLiveness`, `FaceVerification`, `MrzOcrCrossCheck`, `OverallOcrFieldsConfidence`, `PassiveLiveness`) has a `Score` and a `Level` (`HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`). | `GET /api/v1/document/data` returns the data read from the document: `Country`, `DocumentType`, `DocumentVisualResults[]` (`Name`, `Value`, `Confidence`, `PageSide`), `DocumentMrzResults[]` and `AvailableImages`. It holds personal data: keep it on the server. ### Decision logic ```javascript function nextStep(result) { const level = result.Decision.Level; // HIGH | MEDIUM | LOW const live = result.LivenessResult.Result === "Live"; const match = result.FaceMatchResult.IsMatch; if (level === "HIGH" && live && match) return "approved"; // let the user continue if (level === "LOW" || !live || !match) return "rejected"; // not passed: offer a retry or a manual route return "needs_review"; // MEDIUM: additional checks or a person reviews } ``` `MEDIUM` means "suspicious, additional checks recommended". What those checks are is your business decision. ## Errors and limits | Status | When | Body | |---|---|---| | `400` | `instance/create`: a product code that does not exist or is not activated. Result endpoints: no `x-correlation-id` header. | Problem-details JSON, or `{"error": "correlation_id_required"}` | | `401` | Missing or invalid `x-api-key` | Problem-details JSON | | `500` | Result endpoints before the capture finished, or an unknown `CorrelationId` | `{"error": "internal_error", "message": "An unexpected error occurred"}` | Event `ERROR`: restart with a new instance. No rate limit is documented for these calls. ## Test it Use a `test_` key. **A real capture needs a camera and an ID document**, so complete it on a real device. The test is the four steps: instance created on the server, page opens and asks for the camera, the app receives `IDV_SESSION_COMPLETE` and your back end reads `document/result` once. ## Done when - [ ] The instance is created on the server, the `CorrelationId` is stored per user, and the API key is nowhere in the app - [ ] The app asks for camera permission before loading the page and handles a refusal - [ ] The `webEnrolmentUrl` opens in a WebView with JavaScript, inline media and camera access working - [ ] The app receives `IDV_SESSION_COMPLETE` and `ERROR` (exact names) and acts once - [ ] On `IDV_SESSION_COMPLETE` the back end (not the app) calls `document/data` and `document/result` once with `x-api-key` and `x-correlation-id` - [ ] `HIGH`, `MEDIUM` and `LOW` lead to approved, review and rejected, and `ERROR` restarts the flow - [ ] Verified on a real device with a `test_` key ## Related - [Mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/) (canonical human page) and the [iOS sample app](https://github.com/ScreenlyyID/ios-sdk-example) - [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/) - [Get hosted SDK document data](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-document-data/), [Get hosted SDK decision result](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/) - [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/), [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/), [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/) --- # Add identity verification to your web app URL: https://www.screenlyyid.com/docs/guides/identity-verification-web/ > Verify a person's ID document and selfie in your web app with the Instance API and the hosted capture page embedded in an iframe. Follow the four steps exactly. Canonical URL: https://www.screenlyyid.com/docs/guides/identity-verification-web/ > **Agent rules (must follow)** > > - MUST create the instance on your **server** with `POST /api/v1/instance/create`, and MUST store the `CorrelationId` against the user. > - MUST NOT put the API key in browser code, and MUST NOT call the result APIs from the browser. Only your server calls `GET /api/v1/document/data` and `GET /api/v1/document/result`. > - MUST embed the returned `webEnrolmentUrl` in an iframe with `allow="camera; microphone"`, and MUST use the exact event names `IDV_SESSION_COMPLETE` and `ERROR` with the `{ eventName, isError, error }` format. > - MUST check that each message comes from the iframe you created (`event.source`) and from the hosted page's origin (`event.origin`). > - MUST treat `ERROR` as a failure the user can restart. > - MUST NOT build a custom camera, upload, liveness or face-match flow. > - MUST NOT call the direct identity verification endpoints (enrolment, liveness, face match, `data/{sessionId}/...`), even if the developer asks. They are reference only. Identity verification always goes through the Instance API and the hosted `webEnrolmentUrl`. > - MUST NOT call the result endpoints before `IDV_SESSION_COMPLETE`, and MUST NOT poll. > - The canonical human page is [Web app](https://www.screenlyyid.com/docs/integrations/web-app/). If this guide and that page ever differ, tell the developer and follow that page. ## Summary Your server creates an instance, your page embeds the hosted capture page in an iframe, the page tells your page when it is finished, and your server reads the decision. People never leave your site and your API key never reaches the browser. ## When to use it / when not to **Use it for** verifying a person's identity document, face match and liveness in a web app (desktop or mobile browser). **Do not use it for:** - A native or cross-platform mobile app: use [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/). - Redirects, new tabs and pop-ups. The hosted page reports its result with `window.parent.postMessage`, so **only an embedding page (an iframe) receives the events**. A page opened in its own tab or window has no parent to tell, and `RedirectUrl` on the instance request is accepted but the hosted page does not use it. If you cannot use an iframe, use a [no-code link](https://www.screenlyyid.com/docs/getting-started/integration-options/#no-code-links) and read the result from the dashboard or your server. - Checks that need no document or selfie (BIN, phone, email, address, IP, eIDV, AML): see the [guides index](https://www.screenlyyid.com/docs/guides/). ## Before you start - **API key:** `SCREENLYYID_API_KEY` on your **server only**. `test_` for the sandbox, `prod_` for live. See [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key). - **Base URL:** `https://api.screenlyyid.com`. Your page must be served over HTTPS for the camera to work. - **Product:** `idv` in `GlobalScreening`, activated on the account. - **A server you control** with two routes: create a verification, and read its result. The [Express](https://www.screenlyyid.com/docs/recipes/express/), [FastAPI](https://www.screenlyyid.com/docs/recipes/fastapi/) and [Next.js](https://www.screenlyyid.com/docs/recipes/nextjs/) recipes are complete examples of exactly this. ```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": ["idv"], "CustomerIntelligence": []}' # { "CorrelationId": "...", "webEnrolmentUrl": "https://app.screenlyyid.com/idv/..." } ``` ## Use it on its own or stacked Identity verification can run on its own (`GlobalScreening: ["idv"]`) or in the same instance as other checks for the same customer, for example `["idv", "aml", "eidv1"]` for client onboarding. The capture flow does not change: the other checks are server calls that send the same `CorrelationId`. See [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/). Document and selfie identity verification only goes through the Instance API and the hosted flow. The direct identity verification endpoints are reference only. ## Implementation steps The same four steps as the [Mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/) page, in the same order. ### Step 1: Create an instance (server) ```javascript // server route: POST /api/verifications (Node 18+) const r = await fetch("https://api.screenlyyid.com/api/v1/instance/create", { method: "POST", headers: { "x-api-key": process.env.SCREENLYYID_API_KEY, "Content-Type": "application/json" }, body: JSON.stringify({ GlobalScreening: ["idv"], CustomerIntelligence: [] }), }); if (!r.ok) throw new Error(`instance/create failed (HTTP ${r.status})`); const { CorrelationId, webEnrolmentUrl } = await r.json(); // names are exactly these // save CorrelationId against the user; return { verificationId, webEnrolmentUrl } to the browser ``` ### Step 2: Embed the page (browser) ```html ``` `allow="camera; microphone"` is required because the page is on another origin. Add `?skipIntro=true` to the URL to go straight to capture. ### Step 3: Listen for events (browser) ```javascript window.addEventListener("message", async (event) => { const frame = document.getElementById("screenlyyid"); if (!frame || event.source !== frame.contentWindow) return; // only the iframe we created if (event.origin !== new URL(frame.src).origin) return; // and only the hosted page's origin const { eventName, isError, error } = event.data || {}; if (eventName === "IDV_SESSION_COMPLETE" && !isError) { frame.remove(); const r = await fetch(`/api/verifications/${verificationId}`); // YOUR server, Step 4 showOutcome(await r.json()); } else if (eventName === "ERROR") { frame.remove(); offerRestart(error); // create a new instance and embed the new webEnrolmentUrl } }); ``` | Event | Meaning | What to do | |---|---|---| | `IDV_SESSION_COMPLETE` | The document and selfie have been processed and the results are stored. | Remove the iframe and ask your server for the result. | | `ERROR` (`isError` is `true`) | A fatal error while processing the images. | Offer to restart with a new instance. | ### Step 4: Get the result (server) ```javascript // server route: GET /api/verifications/:id (check the verification belongs to the signed-in user first) const headers = { "x-api-key": process.env.SCREENLYYID_API_KEY, "x-correlation-id": correlationId }; const [data, result] = await Promise.all([ fetch("https://api.screenlyyid.com/api/v1/document/data", { headers }).then((r) => r.json()), fetch("https://api.screenlyyid.com/api/v1/document/result", { headers }).then((r) => r.json()), ]); ``` Call once, after the event. A `500 internal_error` means you called before the capture finished. ## Desktop browsers: continue on a phone On a desktop browser the hosted page first shows a QR code. The person scans it with their phone, captures their ID document and selfie there, and the page in your iframe shows their progress. When the phone finishes, your page receives the same message as for an on-device capture: `IDV_SESSION_COMPLETE`, or `ERROR` if the capture failed. Nothing changes in your code: keep listening for the same events and read the result from your server once. - The page offers **Use this device instead** for people who want to capture on the desktop (the iframe then needs `allow="camera; microphone"` as above). - To skip the QR code and go straight to on-device capture, add `handoff=off` to the `webEnrolmentUrl`, for example `...?skipIntro=true&handoff=off`. - Keep the iframe open while the person finishes on their phone. The link belongs to one verification: once it has finished, the QR screen reports that the link can't be continued. - Phones, tablets and mobile WebViews never see the QR code, so the [mobile guide](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) is unchanged. ## Reading the result The same as in the [mobile guide](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/#result): `Decision.Level` (`HIGH`, `MEDIUM`, `LOW`), `LivenessResult.Result` (`Live` or `Not Live`) and `FaceMatchResult.IsMatch`. See [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/). ### Decision logic `HIGH` with a live selfie that matches the ID is approved; `LOW`, a failed liveness check or a face mismatch is rejected; anything else (`MEDIUM`) needs review. ```javascript function nextStep(result) { const level = result.Decision.Level; const live = result.LivenessResult.Result === "Live"; const match = result.FaceMatchResult.IsMatch; if (level === "HIGH" && live && match) return "approved"; if (level === "LOW" || !live || !match) return "rejected"; return "needs_review"; // MEDIUM } ``` ## Errors and limits | Status | When | Body | |---|---|---| | `400` | `instance/create`: a product code that does not exist or is not activated. Result endpoints: no `x-correlation-id` header. | Problem-details JSON, or `{"error": "correlation_id_required"}` | | `401` | Missing or invalid `x-api-key` | Problem-details JSON | | `500` | Result endpoints before the capture finished, or an unknown `CorrelationId` | `{"error": "internal_error", "message": "An unexpected error occurred"}` | No rate limit is documented for these calls. ## Test it With a `test_` key, create a verification and confirm the response has `CorrelationId` and `webEnrolmentUrl`, and that the hosted page loads in the iframe with the camera prompt. **A real capture needs a camera and an ID document**: complete one in a browser to see `IDV_SESSION_COMPLETE` arrive and your server read the result. ## Done when - [ ] The instance is created on the server, the `CorrelationId` is stored per user, and the API key never reaches the browser - [ ] The `webEnrolmentUrl` is embedded in an iframe with `allow="camera; microphone"` over HTTPS - [ ] The message handler checks `event.source` and `event.origin`, and handles `IDV_SESSION_COMPLETE` and `ERROR` (exact names) once, including when the person finishes on their phone (the iframe stays open until then) - [ ] On `IDV_SESSION_COMPLETE` the server (not the browser) calls `document/data` and `document/result` once with `x-api-key` and `x-correlation-id` - [ ] `HIGH`, `MEDIUM` and `LOW` lead to approved, review and rejected, and `ERROR` restarts the flow - [ ] A verification belongs to one user: another user's id returns 404 - [ ] Verified in a browser with a `test_` key ## Related - [Web app](https://www.screenlyyid.com/docs/integrations/web-app/) (canonical human page) - [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) - [Get hosted SDK document data](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-document-data/), [Get hosted SDK decision result](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/) - [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/), [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/), [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/) --- # Run several checks in one session URL: https://www.screenlyyid.com/docs/guides/stacking-checks/ > 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/) --- # Add BIN lookup to your app URL: https://www.screenlyyid.com/docs/guides/bin-lookup/ > Add BIN lookup 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/bin-lookup/ ## Summary BIN lookup takes the first 6 to 10 digits of a payment card number and returns the card's brand, type, issuing country, issuer and whether it is prepaid or commercial. Use it before or during checkout to catch cards that do not match your customer, your region or your risk rules. ## When to use it / when not to **Use it for:** - a card payment at checkout, to check card type, issuing country and prepaid status before you authorise it - you want to compare the card's country with the customer's IP address (send `CustomerIpAddress`) **Do not use it for:** - You want to verify the cardholder's identity: use [Identity verification](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/). - You want to check an email, phone or IP: see [Email](https://www.screenlyyid.com/docs/guides/email-validation/), [Phone](https://www.screenlyyid.com/docs/guides/phone-validation/) and [Device and IP](https://www.screenlyyid.com/docs/guides/device-ip-intelligence/). - Never send a full card number. Send only the first 6 to 10 digits (8 or more digits gives the most accurate result). ## 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 first BIN lookups are free; after that BIN lookups need a BIN check pack or a plan allowance (see [Pricing](https://www.screenlyyid.com/pricing/)). The API answers `402` when the free allowance or the credits are used up and `429` when a daily cap is reached. - **Start with the Instance API.** Every flow starts with `POST /api/v1/instance/create`, listing this product's code (`bin`) 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": ["bin"]}' # { "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 `bin`, 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: BIN + email + IP at checkout (`CustomerIntelligence`: `["bin", "emv", "ipv"]`). 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/bin-lookup` with `x-api-key`, `x-correlation-id` and a JSON body (next section). In a typical app this is the checkout route, before you authorise payment. 3. **Read the response** and apply the [decision logic](https://www.screenlyyid.com/docs/guides/bin-lookup/#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 { "BinNumber": "45717360", "CustomerIpAddress": "203.0.113.7" } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `BinNumber` | string | The first 6, 8 or 10 digits of the card number. Required. | 45717360 | | `CustomerIpAddress` | string | The customer's IP address. Optional. When sent, the `Ip*` fields and `IpMatchesBin` are filled in. | 203.0.113.7 | ### Response ```json { "BinNumber": "45717360", "CardBrand": "VISA/DANKORT", "CardCategory": "DANKORT", "CardType": "DEBIT", "Country": "DENMARK", "CountryCode": "DK", "CountryCode3": "DNK", "CurrencyCode": "DKK", "IpBlocklisted": null, "IpCity": "", "IpCountry": "", "IpCountryCode": "", "IpCountryCode3": "", "IpMatchesBin": false, "IpRegion": "", "IsCommercial": false, "IsPrepaid": false, "Issuer": "JYSKE BANK A/S", "IssuerPhone": "", "IssuerWebsite": null, "Valid": true } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `Valid` | boolean | ★ `false` when the BIN is not recognised (all other fields are empty). | true | | `CardType` | string | ★ `DEBIT`, `CREDIT` and so on. | DEBIT | | `CardBrand` | string | Card scheme. | VISA/DANKORT | | `CardCategory` | string | Card category. | DANKORT | | `IsPrepaid` | boolean | ★ `true` for prepaid cards. | false | | `IsCommercial` | boolean | ★ `true` for commercial or corporate cards. | false | | `CountryCode` | string | ★ Issuing country, ISO 3166 alpha-2. Compare with the billing country. | DK | | `Issuer` | string | Issuing bank. | JYSKE BANK A/S | | `IpMatchesBin` | boolean | ★ Only meaningful when you sent `CustomerIpAddress`: whether the IP's country matches the card's. | false | | `IpBlocklisted` | boolean or null | Whether the IP is on a blocklist. `null` when not checked. | null | ★ = base your decision on this field. ## Decision logic 1. `Valid` is `false`: ask for another card. The BIN does not exist. 2. `IsPrepaid` is `true`: flag for review, or apply your prepaid policy. 3. `CountryCode` differs from the billing country: flag for review. 4. You sent `CustomerIpAddress` and `IpMatchesBin` is `false`: flag for review. 5. Otherwise accept. `IpMatchesBin` `false` is a risk signal, not proof of fraud: travellers and VPN users trigger it. ```javascript function binDecision(bin) { if (!bin.Valid) return { action: "reject", reason: "unknown_bin" }; const flags = []; if (bin.IsPrepaid) flags.push("prepaid"); if (bin.CountryCode !== billingCountryCode) flags.push("country_mismatch"); if (customerIp && !bin.IpMatchesBin) flags.push("ip_country_mismatch"); return flags.length ? { action: "review", reason: flags } : { action: "accept" }; } ``` ## 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": {"": ["The 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"}` | | `402` | `bin_free_allowance_used` or `bin_credits_exhausted` | `{"error": "bin_free_allowance_used", "message": "You have used your free BIN lookups. Buy a BIN check pack to keep going."}`. Buy a BIN check pack or wait for the allowance to renew. | | `429` | `bin_daily_cap_reached` | `{"error": "bin_daily_cap_reached", ...}` with a `Retry-After` header (seconds until 00:00 UTC). | There is no documented per-minute rate limit for BIN lookup. There is a daily cap per account that resets at 00:00 UTC. Use a 15 second timeout and do not retry `4xx` responses. Retry a `500` or a timeout at most once. ## 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: ["bin"] }), }); 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: BIN lookup takes the first 6 to 10 digits of a payment card number and returns the card's brand, type, issuing country, issuer and whether it is prepaid or commercial export async function binLookup(binNumber, customerIp) { const correlationId = await createInstance(); const r = await fetch(`${API}/api/v1/bin-lookup`, { method: "POST", headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" }, body: JSON.stringify({ BinNumber: binNumber, ...(customerIp && { CustomerIpAddress: customerIp }) }), signal: AbortSignal.timeout(15000), }); if (!r.ok) { const error = new Error(`/bin-lookup 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": ["bin"]}, timeout=15, ) r.raise_for_status() return r.json()["CorrelationId"] # spelled exactly like this def bin_lookup(bin_number, customer_ip=None): """Step 2: BIN lookup takes the first 6 to 10 digits of a payment card number and returns the card's brand, type, issuing country, issuer and whether it is prepaid or commercial""" correlation_id = create_instance() r = requests.post( f"{API}/api/v1/bin-lookup", headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id}, json={"BinNumber": bin_number, **({"CustomerIpAddress": customer_ip} if customer_ip else {})}, 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/binLookup/route.js (Next.js App Router). The key is read on the server only. import { binLookup } from "@/lib/screenlyyid"; export const dynamic = "force-dynamic"; export async function POST(request) { const input = await request.json(); try { const { result } = await binLookup(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 lookups, so there are no special test BINs: use the public example BINs below. Free BIN lookups are limited: once they are used the API answers `402 bin_free_allowance_used`. | Input | Expected result | |---|---| | 45717360 | Valid `true`, `CardType` `DEBIT`, `CountryCode` `DK`, `IsPrepaid` `false`, `Issuer` `JYSKE BANK A/S`. | | 411111 | Valid `true`, `CardBrand` `VISA`, `CountryCode` `PL`, `CardType` `DEBIT`. | | 000000 | `200` with `Valid` `false` and empty strings: an unknown BIN is not an HTTP error. | ## Done when - [ ] The API key is read only on the server, from `SCREENLYYID_API_KEY`, and a `test_` key is used while building - [ ] A new instance is created for each lookup and its `CorrelationId` is sent as `x-correlation-id` - [ ] Only the first 6 to 10 digits of the card are sent, never the full number - [ ] `Valid: false` asks the customer for another card, and a prepaid or country-mismatch result is flagged for review - [ ] `402`, `429`, timeouts and `5xx` do not break checkout (a defined fail-open or fail-closed rule applies) - [ ] A test call with `45717360` returns `200` with `CountryCode` `DK` ## Related - [BIN lookup (API reference)](https://www.screenlyyid.com/docs/api-reference/bin-lookup/) - [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) - [Free BIN checker](https://www.screenlyyid.com/bin-checker/) - [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/) --- # Add phone validation to your app URL: https://www.screenlyyid.com/docs/guides/phone-validation/ > Add phone validation 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/phone-validation/ ## Summary Phone validation checks that a phone number exists and is well formed, and returns its country, location, line type and international format. Use it at sign-up or checkout to reject mistyped numbers and to see what kind of line you are dealing with. ## When to use it / when not to **Use it for:** - a phone number field at sign-up, checkout or account recovery - you need the number in international (E.164-style) format before you store it or send an SMS **Do not use it for:** - You need to know whether the number is live on a network right now: use the [HLR lookup](https://www.screenlyyid.com/docs/guides/phone-validation/#hlr) below. - You want to check an email address: [Email validation](https://www.screenlyyid.com/docs/guides/email-validation/). ## 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 phone validation product (`phv`) 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 (`phv`) 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": ["phv"]}' # { "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 `phv`, 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"]`). 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/phone-validate` 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/phone-validation/#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 { "PhoneNumber": "0412345678", "CountryCode": "AU" } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `PhoneNumber` | string | The number, in international format, or in local format together with `CountryCode` or `IpAdress`. Required. | 0412345678 | | `CountryCode` | string | ISO 3166 alpha-2 country to assume for a local-format number. Maximum 2 characters. | US | | `IpAdress` | string | The customer's IP, used to guess the country of a local-format number. (The field name is spelled this way in the API.) | 203.0.113.7 | ### Response ```json { "Valid": true, "Country": "Australia", "CountryCode": "AU", "PrefixNetwork": "Optus", "InternationalNumber": "+61412345678", "Location": "Australia", "LocalNumber": "0412 345 678", "Type": "mobile", "CurrencyCode": "AUD", "InternationalCallingCode": "61", "IsMobile": true, "CountryCode3": "AUS" } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `Valid` | boolean | ★ Whether the number is valid. | true | | `Type` | string | ★ The line type reported by the provider. | (provider value) | | `IsMobile` | boolean | ★ Whether it is a mobile number. | true | | `InternationalNumber` | string | The number in international format. Store this. | +14155552671 | | `CountryCode` | string | Country of the number, ISO 3166 alpha-2. | US | | `Location` | string | Location of the number, where known. | | | `PrefixNetwork` | string | Network the prefix belongs to. | | ★ = base your decision on this field. ## Decision logic 1. `Valid` is `false`: reject the number and ask the customer to correct it. 2. `Valid` is `true`: store `InternationalNumber`, not what the customer typed. 3. Compare `CountryCode` with the customer's country and flag a mismatch for review if it matters to you. 4. If you will send an SMS, check `IsMobile`. Decide what to do with other values of `Type` using the values you see in your own traffic. ```javascript function phoneDecision(p, expectedCountry) { if (!p.Valid) return { action: "reject", reason: "invalid_number" }; const flags = []; if (expectedCountry && p.CountryCode !== expectedCountry) flags.push("country_mismatch"); if (needsSms && !p.IsMobile) flags.push("not_mobile"); return flags.length ? { action: "review", reason: flags, number: p.InternationalNumber } : { action: "accept", number: p.InternationalNumber }; } ``` ## 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": {"": ["The 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 for phone validation. Use a 15 second timeout, do not retry `4xx`, retry a `500` or timeout at most once. ## HLR lookup `POST /api/v1/hlr-lookup` asks the mobile network whether a number is live and which network it is on now. Use it when `phone-validate` is not enough, for example before an expensive SMS or to spot a recently ported number. It uses the same instance, headers and `phv` product. Send `PhoneNumber` (and `CountryCode` for a local-format number): ```json {"PhoneNumber": "+61412345678"} ``` Example response: ```json { "Country": "Australia", "IsPorted": true, "CountryCode": "AU", "Mnc": "01", "NumberType": "mobile", "InternationalNumber": "+61412345678", "OriginNetwork": "YES OPTUS (Singtel Optus Ltd)", "RoamingCountryCode": "", "Imsi": "5050100000", "LocalNumber": "0412 345 678", "Mcc": "505", "HlrStatus": "ok", "HlrValid": true, "CurrentNetwork": "Telstra", "Msin": "", "IsRoaming": false, "Location": "Australia", "Msc": "", "CurrencyCode": "AUD", "InternationalCallingCode": "61", "NumberValid": true, "PortedNetwork": "Telstra", "IsMobile": true, "CountryCode3": "AUS" } ``` Fields to base a decision on: `HlrValid` and `NumberValid` (the number is live), `HlrStatus` (`ok`), `IsMobile` and `NumberType`, `IsPorted`, `CurrentNetwork`, `OriginNetwork`, `IsRoaming`. Treat `HlrValid` `false` as an unreachable number. HLR uses the same `phv` product as `phone-validate`. A repeat call for the same product with the same `CorrelationId` can be refused with `409 duplicate_correlation_id`, so use a separate instance for each call. ## Batch `POST /api/v1/batch-phone-validate`: Validate many numbers in one request, for example to clean a list. ```json [{"PhoneNumber": "+14155552671"}, {"PhoneNumber": "0412345678", "CountryCode": "AU"}] ``` The body is a JSON array of the same objects as the single call. The ScreenlyyID API sets no maximum batch size in its code and the batch endpoint returns the provider's response unchanged, so send modest chunks and a generous timeout. Do not use batch in a live sign-up path. ## 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: ["phv"] }), }); 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: Phone validation checks that a phone number exists and is well formed, and returns its country, location, line type and international format export async function validatePhone(phoneNumber, countryCode) { const correlationId = await createInstance(); const r = await fetch(`${API}/api/v1/phone-validate`, { method: "POST", headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" }, body: JSON.stringify({ PhoneNumber: phoneNumber, ...(countryCode && { CountryCode: countryCode }) }), signal: AbortSignal.timeout(15000), }); if (!r.ok) { const error = new Error(`/phone-validate 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": ["phv"]}, timeout=15, ) r.raise_for_status() return r.json()["CorrelationId"] # spelled exactly like this def validate_phone(phone_number, country_code=None): """Step 2: Phone validation checks that a phone number exists and is well formed, and returns its country, location, line type and international format""" correlation_id = create_instance() r = requests.post( f"{API}/api/v1/phone-validate", headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id}, json={"PhoneNumber": phone_number, **({"CountryCode": country_code} if country_code else {})}, 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/validatePhone/route.js (Next.js App Router). The key is read on the server only. import { validatePhone } from "@/lib/screenlyyid"; export const dynamic = "force-dynamic"; export async function POST(request) { const input = await request.json(); try { const { result } = await validatePhone(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 lookups, so there are no special test numbers: use numbers you control. | Input | Expected result | |---|---| | 0412345678 with CountryCode AU | `Valid` `true`, `InternationalNumber` `+61412345678`, `Type` `mobile`, `IsMobile` `true`, `PrefixNetwork` `Optus`. | | +14155552671 | `Valid` `true`, `CountryCode` `US`, `Type` `unknown`, `IsMobile` `false`: a valid number can still have `Type` `unknown`. | | abc | `200` with `Valid` `false` and empty fields: a bad number is not an HTTP error. | ## Done when - [ ] The API key is read only on the server, from `SCREENLYYID_API_KEY` - [ ] A new instance is created per check and its `CorrelationId` is sent as `x-correlation-id` - [ ] `Valid: false` blocks the form with a message that lets the customer fix the number - [ ] `InternationalNumber` is what you store - [ ] Errors and timeouts do not block sign-up (a defined fallback applies) - [ ] A test call returns `200` with a `test_` key ## Related - [Phone verification (API reference)](https://www.screenlyyid.com/docs/api-reference/phone-verification/) - [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) - [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/) --- # Add email validation and verification to your app URL: https://www.screenlyyid.com/docs/guides/email-validation/ > Add email validation and 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/email-validation/ ## Summary Email validation checks the address and its domain without contacting the mailbox. Email verification also asks the mail server whether the mailbox exists. Use validation to catch typos and throwaway addresses cheaply at sign-up, and verification when a bounce or a fake address costs you something. ## When to use it / when not to **Use it for:** - `email-validate`: a sign-up or newsletter form. It checks syntax, the domain and its mail servers, and flags disposable and free-mail addresses. - `email-verify`: before you send something important, or when fake accounts are a problem. It does everything validation does and also reports the mail server's answer for the mailbox (`Verified`, `SmtpStatus`, `IsCatchAll`, `IsDeferred`). - `batch-email-verify`: clean a list. **Do not use it for:** - Some mail servers accept every address (`IsCatchAll`) or delay their answer (`IsDeferred`). Neither check can prove a mailbox belongs to the person: send a confirmation email if that matters. - You want to check a phone number: [Phone validation](https://www.screenlyyid.com/docs/guides/phone-validation/). ## 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 email verification product (`emv`) 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 (`emv`) 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": ["emv"]}' # { "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 `emv`, 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: BIN + IP + email at checkout (`CustomerIntelligence`: `["bin", "ipv", "emv"]`). 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/email-verify` 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/email-validation/#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 { "Email": "jane.citizen@gmail.com", "FixTypos": true } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `Email` | string | The address to check. | someone@example.com | | `FixTypos` | boolean | Try to correct common typos in the domain. Sent as `false` when omitted. | true | `email-validate` (`POST /api/v1/email-validate`) takes the same body and returns the same fields except the mailbox ones (`Verified`, `SmtpStatus`, `SmtpResponse`). Switch `path` to `/email-validate` to use it. ### Response ```json { "SmtpStatus": "ok", "DomainError": false, "Verified": true, "IsFreemail": true, "IsDisposable": false, "Valid": true, "IsCatchAll": false, "IsDeferred": false, "Provider": "gmail.com", "Domain": "gmail.com", "SmtpResponse": "250 2.1.5 OK ffacd0b85a97d-4ac085bb561si8007213f8f.119 - gsmtp", "SyntaxError": false, "Email": "jane.citizen@gmail.com", "IsPersonal": true } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `Valid` | boolean | ★ Address is syntactically valid and its domain can receive mail. | true | | `SyntaxError` | boolean | ★ The address is malformed. | false | | `DomainError` | boolean | ★ The domain does not exist or cannot receive mail. | false | | `IsDisposable` | boolean | ★ A throwaway-address domain. | false | | `Verified` | boolean | ★ (`email-verify` only) The mail server confirmed the mailbox. | true | | `IsCatchAll` | boolean | (`email-verify`) The server accepts any address, so `Verified` proves little. | false | | `IsDeferred` | boolean | (`email-verify`) The server did not answer yet. | false | | `IsFreemail` | boolean | A free provider such as a webmail service. | false | | `IsPersonal` | boolean | Looks like a personal rather than a role address. | true | | `Email` | string | The address, possibly with typos fixed. | someone@example.com | ★ = base your decision on this field. ## Decision logic 1. `SyntaxError` or `DomainError` is `true`, or `Valid` is `false`: reject and ask the customer to correct it. 2. `IsDisposable` is `true`: block or require another address, according to your policy. 3. `email-verify` only: `Verified` is `true`: accept. `Verified` is `false` and the address is not `IsCatchAll` or `IsDeferred`: reject. Catch-all or deferred: accept, then confirm with an email. 4. Always use the `Email` returned: with `FixTypos` it may differ from what was typed. Ask the customer to confirm a corrected address. ```javascript function emailDecision(e) { if (e.SyntaxError || e.DomainError || !e.Valid) return { action: "reject", reason: "invalid_email" }; if (e.IsDisposable) return { action: "reject", reason: "disposable" }; if (e.Verified === false && !e.IsCatchAll && !e.IsDeferred) return { action: "reject", reason: "mailbox_not_found" }; return { action: "accept", email: e.Email, confirmByEmail: e.IsCatchAll || e.IsDeferred }; } ``` ## 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": {"": ["The 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. `email-verify` contacts a mail server and can be slow: use a 15 to 30 second timeout. Do not retry `4xx`; retry a `500` or timeout at most once. ## Batch `POST /api/v1/batch-email-verify`: Verify many addresses in one request, for example to clean a mailing list. ```json [{"Email": "someone@example.com", "FixTypos": true}, {"Email": "other@example.org", "FixTypos": true}] ``` The body is a JSON array of the same objects as `email-verify`. The ScreenlyyID API sets no maximum batch size in its code, so send modest chunks with a generous timeout, and do not use batch in a live sign-up path. ## 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: ["emv"] }), }); 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: Email validation checks the address and its domain without contacting the mailbox export async function verifyEmail(email) { const correlationId = await createInstance(); const r = await fetch(`${API}/api/v1/email-verify`, { method: "POST", headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" }, body: JSON.stringify({ Email: email, FixTypos: true }), signal: AbortSignal.timeout(15000), }); if (!r.ok) { const error = new Error(`/email-verify 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": ["emv"]}, timeout=15, ) r.raise_for_status() return r.json()["CorrelationId"] # spelled exactly like this def verify_email(email): """Step 2: Email validation checks the address and its domain without contacting the mailbox""" correlation_id = create_instance() r = requests.post( f"{API}/api/v1/email-verify", headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id}, json={"Email": email, "FixTypos": True}, 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/verifyEmail/route.js (Next.js App Router). The key is read on the server only. import { verifyEmail } from "@/lib/screenlyyid"; export const dynamic = "force-dynamic"; export async function POST(request) { const input = await request.json(); try { const { result } = await verifyEmail(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 addresses you control. `email-verify` and `email-validate` count as the same product (`emv`): after one of them, the other with the same `CorrelationId` returns `409 duplicate_correlation_id`, so use a new instance for each. | Input | Expected result | |---|---| | jane.citizen@gmail.com | `email-verify`: `Valid` `true`, `Verified` `true`, `SmtpStatus` `ok`, `IsFreemail` `true`, `IsPersonal` `true`. `email-validate` returns the same without the mailbox fields, plus `DomainStatus` `ok` and `MxIpAddress`. | | not-an-email | `200` with `SyntaxError` `true`, `Valid` `false`, `Verified` `false`, `SmtpStatus` `invalid`. | | someone@example.com | `DomainError` `true`, `IsDisposable` `true`, `Valid` `false`: example domains are not deliverable. | ## Done when - [ ] The API key is read only on the server - [ ] A new instance is created per check and its `CorrelationId` is sent - [ ] Invalid and disposable addresses are rejected with a message the customer can act on - [ ] The returned `Email` (typo-fixed) is confirmed with the customer before it is stored - [ ] Catch-all and deferred results trigger a confirmation email instead of a hard accept - [ ] Errors and timeouts do not block sign-up ## Related - [Email verification (API reference)](https://www.screenlyyid.com/docs/api-reference/email-verification/) - [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) - [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/) --- # Add address verification to your app URL: https://www.screenlyyid.com/docs/guides/address-verification/ > 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": "", "TransmissionResults": "", "TotalRecords": "1", "Records": [ { "RecordId": "1", "Results": "", "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": {"": ["The 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/) --- # Add device and IP intelligence to your app URL: https://www.screenlyyid.com/docs/guides/device-ip-intelligence/ > Add device and IP intelligence 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/device-ip-intelligence/ ## Summary Device and IP intelligence looks at the IP address, host name and browser (user agent) behind a request. Four endpoints cover where an IP is and whether it is a VPN or proxy (`ip-probe-verify`), whether it is on a blocklist (`ip-blocklist-verify`), a host's reputation (`host-reputation-verify`) and what device a user agent is (`ua-lookup-verify`). ## When to use it / when not to **Use it for:** - sign-up, login or checkout: is the visitor behind a VPN, proxy, Tor or a hosting provider, or on a blocklist - you want the visitor's country, or whether the browser is a webview or mobile **Do not use it for:** - An IP is a signal, not an identity: many real people use VPNs. Use it to decide when to ask for more, not to block on its own. - You want to check a card against an IP: use [BIN lookup](https://www.screenlyyid.com/docs/guides/bin-lookup/) with `CustomerIpAddress`. ## 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 device and IP product code is `ipv`. In the current API code the four device endpoints do not enforce product activation (the check is switched off), but create the instance with `ipv` anyway so the checks are recorded against the customer. - **Start with the Instance API.** Every flow starts with `POST /api/v1/instance/create`, listing this product's code (`ipv`) 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": ["ipv"]}' # { "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 `ipv`, 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: BIN + IP + email at checkout (`CustomerIntelligence`: `["bin", "ipv", "emv"]`). 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/ip-probe-verify` 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/device-ip-intelligence/#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 { "IpAdress": "8.8.8.8" } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `IpAdress` | string | ip-probe-verify and ip-blocklist-verify: the IP address to check. Required. (The name is spelled this way in the API.) | 8.8.8.8 | | `VPNLookup` | boolean | ip-blocklist-verify only: also check whether the IP is a VPN. | true | | `Host` | string | host-reputation-verify: the host name or IP. Required. | example.com | | `ListRating` | integer | host-reputation-verify: minimum blocklist rating to count. Default 3. | 3 | | `UserAgent` | string | ua-lookup-verify: the browser user-agent string. Required. | Mozilla/5.0 ... | The other endpoints in this product: `POST /api/v1/ip-blocklist-verify`, `POST /api/v1/host-reputation-verify`, `POST /api/v1/ua-lookup-verify`. Each takes its own body (see the request table) and the same headers. ### Response ```json { "RegionCode": "CA", "Country": "United States of America", "CountryCode": "US", "ProviderDomain": "cloud.google.com", "City": "Mountain View", "VpnDomain": "", "IsVpn": false, "AsCidr": "8.8.8.0/24", "Valid": true, "ProviderType": "hosting", "Hostname": "dns.google", "AsAge": 34, "ContinentCode": "NA", "IsBogon": false, "Ip": "8.8.8.8", "AsCountryCode": "US", "ProviderDescription": "Cloud Computing Services Google Cloud: Meet your business challenges head on with cloud computing services from Google, including data management, hybrid & multi-cloud, and AI & ML", "AsCountryCode3": "USA", "IsV4Mapped": false, "IsIsp": false, "ProviderWebsite": "https://cloud.google.com", "AsDescription": "Google LLC, Google, YouTube (for Google Fiber see AS16591 record), GOOGLE, US, GOGL", "IsHosting": true, "AsDomains": [ "cloud.google.com", "about.google" ], "HostDomain": "dns.google", "IsProxy": false, "CurrencyCode": "USD", "Region": "California", "Asn": "15169", "CountryCode3": "USA", "IsV6": false } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `IsVpn` | boolean | ★ ip-probe-verify: the IP belongs to a VPN. | false | | `IsProxy` | boolean | ★ The IP is a proxy. | false | | `IsHosting` | boolean | ★ A hosting or data-centre IP (not a typical home user). | false | | `IsBogon` | boolean | ★ A reserved or unroutable address. | false | | `CountryCode` | string | Country of the IP, ISO 3166 alpha-2. | US | | `IsListed` | boolean | ★ ip-blocklist-verify and host-reputation-verify: appears on a blocklist. | false | | `IsTor / IsBot / IsSpamBot / IsMalware / IsExploitBot` | boolean | ★ ip-blocklist-verify: the kind of listing. | false | | `ListCount` | integer | Number of blocklists that list it. | 0 | | `IsMobile / IsWebview / Type` | boolean / string | ua-lookup-verify: the device type. | true | ★ = base your decision on this field. ## Decision logic 1. `IsBogon` is `true`: reject (not a real client address). 2. `IsListed`, `IsTor`, `IsBot`, `IsSpamBot`, `IsMalware` or `IsExploitBot` is `true`: block, or require stronger verification. 3. `IsVpn`, `IsProxy` or `IsHosting` is `true`: flag for review. Do not block on this alone. 4. Compare `CountryCode` with the country in the customer's other data (card, phone, address). ```javascript function ipDecision(probe, blocklist) { if (probe.IsBogon) return { action: "reject", reason: "bogon" }; if (blocklist && (blocklist.IsListed || blocklist.IsTor || blocklist.IsBot || blocklist.IsMalware)) return { action: "block", reason: "blocklisted" }; const flags = []; if (probe.IsVpn) flags.push("vpn"); if (probe.IsProxy) flags.push("proxy"); if (probe.IsHosting) flags.push("hosting"); return flags.length ? { action: "review", reason: flags } : { action: "accept" }; } ``` ## 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": {"": ["The 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 short timeout (5 to 10 seconds) in a live path and fail open to review if it expires. ## 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: ["ipv"] }), }); 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: Device and IP intelligence looks at the IP address, host name and browser (user agent) behind a request export async function probeIp(ip) { const correlationId = await createInstance(); const r = await fetch(`${API}/api/v1/ip-probe-verify`, { method: "POST", headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" }, body: JSON.stringify({ IpAdress: ip }), signal: AbortSignal.timeout(15000), }); if (!r.ok) { const error = new Error(`/ip-probe-verify 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": ["ipv"]}, timeout=15, ) r.raise_for_status() return r.json()["CorrelationId"] # spelled exactly like this def probe_ip(ip): """Step 2: Device and IP intelligence looks at the IP address, host name and browser (user agent) behind a request""" correlation_id = create_instance() r = requests.post( f"{API}/api/v1/ip-probe-verify", headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id}, json={"IpAdress": ip}, 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/probeIp/route.js (Next.js App Router). The key is read on the server only. import { probeIp } from "@/lib/screenlyyid"; export const dynamic = "force-dynamic"; export async function POST(request) { const input = await request.json(); try { const { result } = await probeIp(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 lookups, so there are no special test values. 8.8.8.8 is a public DNS address, so it shows `IsHosting` `true`: use your own public IP for a typical home-user result. | Input | Expected result | |---|---| | ip-probe-verify 8.8.8.8 | `CountryCode` `US`, `IsHosting` `true`, `ProviderType` `hosting`, `IsVpn` `false`, `IsProxy` `false`, `IsBogon` `false`. | | ip-blocklist-verify 8.8.8.8 | `IsListed` `false`, `IsTor` `false`, `IsVpn` `false`. | | host-reputation-verify example.com | `HostInfos[]` with `IsListed` `false` for each list checked. | | ua-lookup-verify an iPhone Safari user agent | `DeviceModel` `iPhone`, `Os` `iOS 17`, `DeviceBrand` `Apple`. | ## Done when - [ ] The API key is read only on the server - [ ] The client IP comes from your server (the real remote address or your proxy's trusted header), never from a field the browser can set - [ ] A new instance is created per check and its `CorrelationId` is sent - [ ] VPN and proxy results lead to review, not an automatic block - [ ] Errors and timeouts do not break sign-up or checkout - [ ] A test call returns `200` with a `test_` key ## Related - [Device verification (API reference)](https://www.screenlyyid.com/docs/api-reference/device-verification/) - [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) - [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/) --- # Add electronic identity verification (eIDV) to your app URL: https://www.screenlyyid.com/docs/guides/electronic-identity-verification/ > Add electronic identity verification (eIDV) 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/electronic-identity-verification/ ## Summary Electronic identity verification (eIDV) checks a person's name, date of birth, address, phone or email against government, credit and other data sources, without a document or a selfie. A 1x1 check needs a match on one data source; a 2x2 check needs matches on two. ## When to use it / when not to **Use it for:** - `eid-validate-1x1` (`eidv1`): a lower-friction check where one source match is enough - `eid-validate-2x2` (`eidv2`): stricter, for example where regulation expects two independent sources - Tranche 2 client onboarding in Australia, alongside AML screening **Do not use it for:** - 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. - You only need to check an address format: [Address verification](https://www.screenlyyid.com/docs/guides/address-verification/). ## 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 product must be activated on the account: `eidv1` for 1x1 and `eidv2` for 2x2. They are listed in `GlobalScreening` in the instance call. eIDV is billed per check: see the [pricing page](https://www.screenlyyid.com/pricing/). - **Start with the Instance API.** Every flow starts with `POST /api/v1/instance/create`, listing this product's code (`eidv1`) in `GlobalScreening`. 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": ["eidv1"], "CustomerIntelligence": []}' # { "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 `eidv1`, 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: IDV via the hosted flow + AML screening + eIDV for Tranche 2 client onboarding (`GlobalScreening`: `["idv", "aml", "eidv1"]`). Only the direct identity verification endpoints are reference only. Document and selfie identity verification goes through the Instance API and the hosted flow; every other product, including this one, can be called on its own or stacked. ## 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/eid-validate-1x1` 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/electronic-identity-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 { "Identity": { "Completename": "Jane Citizen", "Dob": "1990-01-01" }, "Address": { "AddressLine1": "1 Example St", "Locality": "Sydney", "PostalCode": "2000", "CountryCode": "AU" }, "Phone": { "PhoneNumber": "+61400000000" }, "Email": { "FullEmailAddress": "jane@example.com" } } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `Identity` | object | `Completename`, `Givenfullname`, `SurnameFirst`, `Nationalid`, `Dob`. | { "Completename": "Jane Citizen" } | | `Address` | object | `AddressLine1`, `AddressLine2`, `HouseNumber`, `HouseNumberAddition`, `Thoroughfare`, `Locality`, `PostalCode`, `Province`, `CountryCode`. | { "CountryCode": "AU" } | | `Phone` | object | `PhoneNumber`. | { "PhoneNumber": "+61..." } | | `Email` | object | `FullEmailAddress`. | { "FullEmailAddress": "..." } | The other endpoints in this product: `POST /api/v1/eid-validate-2x2`. Each takes its own body (see the request table) and the same headers. ### Response ```json { "Codes": { "Reliability": "...", "Adaptation": "...", "DetailCode": "...", "CodesDetailList": "..." }, "Identity": { "Completename": "..." }, "Address": { "Thoroughfare": "..." }, "Phone": { "PhonePhoneNumber": "..." }, "Email": { "EmailFullEmailAddress": "..." } } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `Codes.Reliability` | string | ★ How reliable the match is. | | | `Codes.DetailCode` | string | ★ The detail code for the match. | | | `Codes.CodesDetailList` | string | ★ Detailed per-field result codes. | | | `Codes.Adaptation` | string | Adaptation code. | | | `Identity / Address / Phone / Email` | object | The matched data per section. | | ★ = base your decision on this field. ## Decision logic 1. Base the decision on `Codes` (`Reliability`, `DetailCode`, `CodesDetailList`): they say which fields matched and how reliably. The meanings of the codes are in the [eIDV reference](https://www.screenlyyid.com/docs/api-reference/electronic-identity-verification/). 2. Choose 1x1 or 2x2 by the assurance you need. Use 2x2 when you need two independent sources to agree. 3. A non-match is not proof of fraud: send the person to the [hosted identity verification](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) or to manual review. ```javascript function eidvDecision(res) { const codes = res.Codes; if (!codes) return { action: "review", reason: "no_codes" }; // map codes.Reliability / codes.DetailCode to accept, step up or review using the table in the eIDV reference return { action: "review", codes }; } ``` ## 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": {"": ["The 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 30 second timeout. Do not retry `4xx`. eIDV is billed per check, so retry a `500` or timeout at most once. ## 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: ["eidv1"], CustomerIntelligence: [] }), }); 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: Electronic identity verification (eIDV) checks a person's name, date of birth, address, phone or email against government, credit and other data sources, without a document or a selfie export async function eidv1x1(person) { const correlationId = await createInstance(); const r = await fetch(`${API}/api/v1/eid-validate-1x1`, { method: "POST", headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" }, body: JSON.stringify(person), signal: AbortSignal.timeout(15000), }); if (!r.ok) { const error = new Error(`/eid-validate-1x1 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": ["eidv1"], "CustomerIntelligence": []}, timeout=15, ) r.raise_for_status() return r.json()["CorrelationId"] # spelled exactly like this def eidv_1x1(person): """Step 2: Electronic identity verification (eIDV) checks a person's name, date of birth, address, phone or email against government, credit and other data sources, without a document or a selfie""" correlation_id = create_instance() r = requests.post( f"{API}/api/v1/eid-validate-1x1", headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id}, json=person, 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/eidv1x1/route.js (Next.js App Router). The key is read on the server only. import { eidv1x1 } from "@/lib/screenlyyid"; export const dynamic = "force-dynamic"; export async function POST(request) { const input = await request.json(); try { const { result } = await eidv1x1(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 There are no special test identities: use people you can check. Results depend on the countries and data sources enabled for the account. | Input | Expected result | |---|---| | a person that exists in the data sources | `200` with `Codes` (`Reliability`, `DetailCode`, `CodesDetailList`) and the matched `Identity`, `Address`, `Phone` and `Email` sections. | | a person that does not exist | `200` with `Codes` that show no match: not an HTTP error. | ## Done when - [ ] The API key is read only on the server - [ ] The instance lists `eidv1` or `eidv2` in `GlobalScreening` and the `CorrelationId` is sent as `x-correlation-id` - [ ] The right endpoint is called for the product listed (1x1 for `eidv1`, 2x2 for `eidv2`) - [ ] The decision uses `Codes`, and a non-match leads to step-up or review, not an automatic rejection - [ ] No document or selfie capture is built: that only goes through the hosted flow - [ ] A test call returns `200` with a `test_` key ## Related - [Electronic identity verification (API reference)](https://www.screenlyyid.com/docs/api-reference/electronic-identity-verification/) - [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) - [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/) --- # Add AML screening to your app URL: https://www.screenlyyid.com/docs/guides/aml-screening/ > Add AML screening 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/aml-screening/ ## Summary AML screening checks a person or an entity (company, organisation or vessel) against sanctions and politically exposed person (PEP) lists and returns the matches with scores and reasons. Use it when you onboard a customer or counterparty, and whenever your obligations require a sanctions check. ## When to use it / when not to **Use it for:** - `screening/person`: an individual (name, date of birth, nationality, country, address) - `screening/entity`: a company, organisation or vessel (name, aliases, registration number, jurisdiction) **Do not use it for:** - 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. - A match is not a conviction: a human reviews every `potential_match`. ## 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 `aml` product must be activated on the account and is listed in `GlobalScreening` in the instance call. Screening is rate limited per account (`429 rate_limited`). - **Start with the Instance API.** Every flow starts with `POST /api/v1/instance/create`, listing this product's code (`aml`) in `GlobalScreening`. 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": ["aml"], "CustomerIntelligence": []}' # { "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 `aml`, 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: IDV via the hosted flow + AML screening + eIDV for Tranche 2 client onboarding, or address + phone + AML for a marketplace seller. Only the direct identity verification endpoints are reference only. Document and selfie identity verification goes through the Instance API and the hosted flow; every other product, including this one, can be called on its own or stacked. ## 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/screening/person` with `x-api-key`, `x-correlation-id` and a JSON body (next section). In a typical app this is the onboarding handler, before you activate the customer. 3. **Read the response** and apply the [decision logic](https://www.screenlyyid.com/docs/guides/aml-screening/#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 { "GivenName": "Jane", "FamilyName": "Citizen", "DateOfBirth": "1990-01-01", "Nationality": "AU", "Country": "AU" } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `GivenName / MiddleName / FamilyName` | string | The person's names. | Jane | | `DateOfBirth` | string | `YYYY`, `YYYY-MM` or `YYYY-MM-DD`. A date of birth sharpens the match. | 1990-01-01 | | `Nationality` | string | ISO 3166 alpha-2. | AU | | `Country` | string | Country of the person. | AU | | `Address` | object | `Line1`, `Locality`, `State`, `PostalCode`, `Country`. | | | `Sources` | array | `"dfat"`, `"opensanctions"`. Default: both. | ["dfat"] | | `Options` | object | `Threshold` (0.5 to 0.99, default 0.8), `Limit` (1 to 20 matches per source, default 5), `Categories` (`"sanction"`, `"pep"`). | { "Threshold": 0.8 } | The other endpoints in this product: `POST /api/v1/screening/entity`. Each takes its own body (see the request table) and the same headers. ### Response ```json { "correlationId": "d53e3f4d-9a58-4955-8836-a6b8817ea0a3", "subjectType": "person", "screenedAt": "2026-11-21T05:39:17.7925872+00:00", "outcome": "incomplete", "sources": [ { "source": "dfat", "status": "ok", "listVersion": "2026-11-17", "listVersionId": 6, "dataset": null, "algorithm": null, "matchCount": 0, "error": null }, { "source": "opensanctions", "status": "ok", "listVersion": null, "listVersionId": null, "dataset": null, "algorithm": null, "matchCount": 0, "error": null } ], "matches": [] } ``` | Field | Type | Meaning | Example | |---|---|---|---| | `outcome` | string | ★ `clear`, `potential_match` or `incomplete`. | incomplete | | `matches[]` | array | ★ Each match: `name`, `score`, `matched`, `categories`, `lists`, `dateOfBirth`, `reasons`. | [] | | `sources[]` | array | ★ Per source: `source`, `status` (`ok` when the source answered), `matchCount`, `error`. Check that every source is `ok`. | | | `correlationId` | string | The instance's id. | | | `screenedAt` | string | When the screening ran (UTC). | | ★ = base your decision on this field. ## Decision logic 1. `outcome` is `potential_match`: stop the onboarding and send the case to a person to review the matches. Do not auto-reject. 2. `outcome` is `clear`: every source answered and nothing matched. Continue. 3. `outcome` is `incomplete`: at least one source did not return `ok` (see `sources[].status`). **Do not treat this as clear.** Retry later or review manually. 4. Keep the full response with the customer record as your audit trail. ```javascript function amlDecision(res) { if (res.outcome === "potential_match") return { action: "review", matches: res.matches }; if (res.outcome === "incomplete") return { action: "retry_or_review", sources: res.sources }; return { action: "accept" }; // "clear": every source answered and nothing matched } ``` ## 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": {"": ["The 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"}` | | `429` | Screening rate limit reached | `{"error": "rate_limited"}` | | `502` | Screening is temporarily unavailable | `{"error": "screening_unavailable"}` | Screening is rate limited per account (`429 rate_limited`; the limit is not published). Retry `502` and `429` with a delay; do not retry `400`. Responses use camelCase property names (unlike most other products). ## 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: ["aml"], CustomerIntelligence: [] }), }); 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: AML screening checks a person or an entity (company, organisation or vessel) against sanctions and politically exposed person (PEP) lists and returns the matches with scores and reasons export async function screenPerson(person) { const correlationId = await createInstance(); const r = await fetch(`${API}/api/v1/screening/person`, { method: "POST", headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" }, body: JSON.stringify(person), signal: AbortSignal.timeout(15000), }); if (!r.ok) { const error = new Error(`/screening/person 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": ["aml"], "CustomerIntelligence": []}, timeout=15, ) r.raise_for_status() return r.json()["CorrelationId"] # spelled exactly like this def screen_person(person): """Step 2: AML screening checks a person or an entity (company, organisation or vessel) against sanctions and politically exposed person (PEP) lists and returns the matches with scores and reasons""" correlation_id = create_instance() r = requests.post( f"{API}/api/v1/screening/person", headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id}, json=person, 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/screenPerson/route.js (Next.js App Router). The key is read on the server only. import { screenPerson } from "@/lib/screenlyyid"; export const dynamic = "force-dynamic"; export async function POST(request) { const input = await request.json(); try { const { result } = await screenPerson(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 `outcome` is `clear` only when every source returns `status` `ok` and nothing matches; if a source is unavailable (for example an error) a no-match screening is `incomplete`. Your code must handle `incomplete`. | Input | Expected result | |---|---| | Vladimir Vladimirovich Putin, born 1952-10-07, nationality RU | `outcome` `potential_match` with a DFAT match, `score` 1, category `sanction`. Use this public example to test the review path. | | Jane Citizen, country AU | No matches: `outcome` is `clear` when every source answered, and `incomplete` when a source did not. | ## Done when - [ ] The API key is read only on the server - [ ] The instance lists `aml` in `GlobalScreening` and the `CorrelationId` is sent as `x-correlation-id` - [ ] `potential_match` stops the flow and creates a manual review, never an automatic rejection - [ ] `incomplete` is retried or reviewed, never treated as `clear` - [ ] The full response is stored as the audit record - [ ] A test call with the example above returns `potential_match` ## Related - [Sanctions and AML (API reference)](https://www.screenlyyid.com/docs/api-reference/sanctions-and-aml/) - [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) - [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/) --- # Reference only (do not integrate) URL: https://www.screenlyyid.com/docs/api-reference/identity-verification/ Reference only. Don't integrate these endpoints. To verify identity, create an instance with the Instance API and follow the identity verification guide (mobile or web). This applies only to the direct identity verification endpoints listed here: BIN, phone, email, address, device and IP, eIDV and AML screening can each be used on their own or stacked. - Create document session `POST /api/v1/enrolment/initialize`: https://www.screenlyyid.com/docs/api-reference/identity-verification/create-document-session/ - Enrol document `POST /api/v1/enrolment/document`: https://www.screenlyyid.com/docs/api-reference/identity-verification/enrol-document/ - Enrol selfie `POST /api/v1/enrolment/face`: https://www.screenlyyid.com/docs/api-reference/identity-verification/enrol-selfie/ - Document image list `GET /api/v1/data/{sessionId}/images`: https://www.screenlyyid.com/docs/api-reference/identity-verification/document-image-list/ - Download primary face image `GET /api/v1/data/{sessionId}/images/primary_face`: https://www.screenlyyid.com/docs/api-reference/identity-verification/document-image-download-primary-face/ - Document image download `GET /api/v1/data/{sessionId}/images/{imageName}`: https://www.screenlyyid.com/docs/api-reference/identity-verification/document-image-download/ - Liveness check `POST /api/v1/liveness`: https://www.screenlyyid.com/docs/api-reference/identity-verification/liveness-check/ - Face match `POST /api/v1/facematch`: https://www.screenlyyid.com/docs/api-reference/identity-verification/face-match/ - Complete enrolment `POST /api/v1/enrolment/complete`: https://www.screenlyyid.com/docs/api-reference/identity-verification/complete-enrolment/ - Get OCR data `GET /api/v1/data/{sessionId}/document/result`: https://www.screenlyyid.com/docs/api-reference/identity-verification/get-ocr-data/ - Get decision results `GET /api/v1/data/{sessionId}/decision/result`: https://www.screenlyyid.com/docs/api-reference/identity-verification/get-decision-results/ --- # Authentication URL: https://www.screenlyyid.com/docs/authentication/ > How ScreenlyyID authenticates API requests with an API key and a per-session correlation ID. Canonical URL: https://www.screenlyyid.com/docs/authentication/ The ScreenlyyID API uses **API keys**, created in the dashboard, and a **session key** to authenticate requests. You can view and manage your API keys in the [ScreenlyyID dashboard](https://admin.screenlyyid.com/). > **Warning:** > Your API keys carry many privileges. Keep them secure and never share them in publicly accessible places such as GitHub or client-side code. Pass your API key in the `x-api-key` header. All API requests must be made over HTTPS. Calls made over plain HTTP will fail, and so will requests without authentication. ## Session keys As well as your `x-api-key`, you must pass a temporary token in the `x-correlation-id` header. Create the correlation ID at the start of each request flow with the [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/). Think of the correlation ID as a session token. Use it for one set of API calls for a single customer, until that sequence is finished. ## Product codes When you create an instance you also supply the product codes that session can access. A product must be activated on your account for its code to work. | Product | Code | Class | |---|---|---| | Identity verification | `idv` | Global screening | | Sanctions, PEP and watchlist screening | `aml` | Global screening | | Electronic identity verification 1x1 | `eidv1` | Global screening | | Electronic identity verification 2x2 | `eidv2` | Global screening | | Address verification | `adv` | Customer intelligence | | Email validation and enrichment | `emv` | Customer intelligence | | Phone validation and enrichment | `phv` | Customer intelligence | | IP and device analysis | `ipv` | Customer intelligence | | BIN lookup | `bin` | Customer intelligence | Codes for the **Global screening** class go in the `GlobalScreening` array of the instance request. Codes for **Customer intelligence** go in the `CustomerIntelligence` array. --- # Create instance URL: https://www.screenlyyid.com/docs/authentication/create-instance/ > POST /api/v1/instance/create. Creates a correlation ID, which you pass in the x-correlation-id header on every later call, alongside your API key, until the sequence is finished. Canonical URL: https://www.screenlyyid.com/docs/authentication/create-instance/ Integrating this? Follow the [Integration guides](https://www.screenlyyid.com/docs/guides/). Creates a **correlation ID**, which you pass in the `x-correlation-id` header on every later call, alongside your API key, until the sequence is finished. Think of it as a session token: use it for one set of API calls for a single customer. The request also defines which ScreenlyyID products the session can access. Put `idv`, `aml`, `eidv1` and `eidv2` in `GlobalScreening`, and `adv`, `emv`, `phv`, `ipv` and `bin` in `CustomerIntelligence`. The products must be activated on your account. See [product codes](https://www.screenlyyid.com/docs/authentication/#product-codes). For identity verification the response also includes a `webEnrolmentUrl` you can load in a WebView. See [Mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/). **POST** `https://api.screenlyyid.com/api/v1/instance/create` ## Headers | Name | Type | Required | Description | |---|---|---|---| | `x-api-key` | string | Yes | Your ScreenlyyID API key | ## Request body | Field | Type | Required | Description | |---|---|---|---| | `FirstName` | string | No | | | `LastName` | string | No | | | `ClientLookupId` | string (uuid) | No | | | `RedirectUrl` | string | No | | | `GlobalScreening` | array of string | No | | | `CustomerIntelligence` | array of string | No | | ## Responses | Status | Description | |---|---| | `200` | Successful response | | `400` | Bad request | | `401` | Unauthorized | ## Code samples ```bash curl --request POST \ --url 'https://api.screenlyyid.com/api/v1/instance/create' \ --header 'x-api-key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "FirstName": "Jane", "LastName": "Citizen", "ClientLookupId": "00000000-0000-0000-0000-000000000000", "RedirectUrl": "https://example.com/done", "GlobalScreening": [ "idv" ], "CustomerIntelligence": [ "emv" ] }' ``` ```javascript const body = { "FirstName": "Jane", "LastName": "Citizen", "ClientLookupId": "00000000-0000-0000-0000-000000000000", "RedirectUrl": "https://example.com/done", "GlobalScreening": [ "idv" ], "CustomerIntelligence": [ "emv" ] }; const response = await fetch( "https://api.screenlyyid.com/api/v1/instance/create", { "method": "POST", "headers": { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" }, "body": JSON.stringify(body) } ); const result = await response.json(); ``` ```python import requests payload = { "FirstName": "Jane", "LastName": "Citizen", "ClientLookupId": "00000000-0000-0000-0000-000000000000", "RedirectUrl": "https://example.com/done", "GlobalScreening": [ "idv" ], "CustomerIntelligence": [ "emv" ] } response = requests.post( 'https://api.screenlyyid.com/api/v1/instance/create', headers={ "x-api-key": "YOUR_API_KEY" }, json=payload ) result = response.json() ``` ```csharp using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var json = @"{ ""FirstName"": ""Jane"", ""LastName"": ""Citizen"", ""ClientLookupId"": ""00000000-0000-0000-0000-000000000000"", ""RedirectUrl"": ""https://example.com/done"", ""GlobalScreening"": [ ""idv"" ], ""CustomerIntelligence"": [ ""emv"" ] }"; var content = new StringContent(json, Encoding.UTF8, "application/json"); var response = await client.PostAsync("https://api.screenlyyid.com/api/v1/instance/create", content); response.EnsureSuccessStatusCode(); var result = await response.Content.ReadAsStringAsync(); ``` --- # Signing up URL: https://www.screenlyyid.com/docs/getting-started/signing-up/ > Create a ScreenlyyID account so you can generate API keys and run checks. Canonical URL: https://www.screenlyyid.com/docs/getting-started/signing-up/ You need an account before you can run any ScreenlyyID check. 1. Go to the [pricing page](https://www.screenlyyid.com/pricing/), choose a plan and register with a valid business email. For enterprise pricing, use the [contact form](https://www.screenlyyid.com/contact-us/) and the sales team will help. 2. Verify your business email by clicking the link in the verification email we send you. 3. Complete your company and contact details. ScreenlyyID requires these before you can run checks. You now have a ScreenlyyID account. Next, [choose the products](https://www.screenlyyid.com/docs/getting-started/choose-a-product/) you want to use and create an API key in the [dashboard](https://admin.screenlyyid.com/). --- # Choose a product URL: https://www.screenlyyid.com/docs/getting-started/choose-a-product/ > The ScreenlyyID products, what each one does and the product code you pass to the API. Canonical URL: https://www.screenlyyid.com/docs/getting-started/choose-a-product/ ScreenlyyID products can be used together or on their own. With the web and mobile integrations you identify the product you want with a **product code**. You also pass product codes to the [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) to define what a session can access. > **Note:** > A product must be activated on your account before its code works. ## Product codes | Product | What it does | Code | API reference | |---|---|---|---| | Remote identity verification | Captures an identity document, checks it is authentic, then performs a face match and liveness check against a selfie. | `idv` | [Identity verification](https://www.screenlyyid.com/docs/api-reference/identity-verification/) | | Electronic identity verification (1x1) | Verifies a name, date of birth and national ID number against one government, credit, telco, utility or consumer data source. No document or selfie needed. | `eidv1` | [eIDV](https://www.screenlyyid.com/docs/api-reference/electronic-identity-verification/) | | Electronic identity verification (2x2) | Same inputs as 1x1, but requires a match against two data sources. | `eidv2` | [eIDV](https://www.screenlyyid.com/docs/api-reference/electronic-identity-verification/) | | AML screening | Checks a name and date of birth against global sanctions, PEP and government watchlists. | `aml` | [Sanctions and AML](https://www.screenlyyid.com/docs/api-reference/sanctions-and-aml/) | | Address verification | Validates and standardises addresses in over 245 countries and territories. | `adv` | [Address verification](https://www.screenlyyid.com/docs/api-reference/address-verification/) | | Phone verification | Validates a phone number in real time: live numbers, country, carrier, location and status. | `phv` | [Phone verification](https://www.screenlyyid.com/docs/api-reference/phone-verification/) | | Email verification | Confirms an email address exists using SMTP checks, and flags disposable, freemail, role-based and other risky addresses. | `emv` | [Email verification](https://www.screenlyyid.com/docs/api-reference/email-verification/) | | IP and device analysis | Probes an IP address for VPN, proxy and hosting signals, blocklist status and host reputation. | `ipv` | [Device verification](https://www.screenlyyid.com/docs/api-reference/device-verification/) | | Bank identification number | Helps stop fraudulent card transactions by verifying card BINs in real time. | `bin` | [BIN lookup](https://www.screenlyyid.com/docs/api-reference/bin-lookup/) | --- # Choose an integration option URL: https://www.screenlyyid.com/docs/getting-started/integration-options/ > Run checks directly in the dashboard, send no-code links, or integrate the ScreenlyyID SDK into your own app. Canonical URL: https://www.screenlyyid.com/docs/getting-started/integration-options/ The right way to run checks depends on your business requirements and how you engage customers. | Option | Best for | |---|---| | [Direct](https://www.screenlyyid.com/docs/getting-started/integration-options/#direct) | Ad-hoc, single checks using information you already have. | | [No-code links](https://www.screenlyyid.com/docs/getting-started/integration-options/#no-code-links) | Sending a link or QR code so the customer completes verification on their own device. | | [Application integration](https://www.screenlyyid.com/docs/getting-started/integration-options/#application-integration) | Keeping customers inside your own mobile or web app. | ## Direct Run single verifications in the [ScreenlyyID dashboard](https://admin.screenlyyid.com/) using the **Run Check** menu. You need all the information for the person being checked. These checks can be run directly: - Electronic identity verification (eIDV) - AML sanctions, PEP and watchlist screening - Address, phone and email verification - BIN verification > **Note:** > Remote identity verification cannot be run directly from the dashboard, because it requires the customer to capture an identity document and a selfie. Use a no-code link or an application integration. ## No-code links A no-code link, or a QR code, lets someone complete the verification on their own device. Results are sent back to the ScreenlyyID dashboard. Every product can be used through a no-code link. You can create links in two ways: in the dashboard, or with a single API call. ## Application integration If you want to keep users inside your own app, ScreenlyyID can be integrated with any platform or device. Start with [How it works](https://www.screenlyyid.com/docs/getting-started/how-it-works/), then choose a collection method: - [Mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/) - [Web app](https://www.screenlyyid.com/docs/integrations/web-app/) - [Custom integration](https://www.screenlyyid.com/docs/integrations/custom-integration/) --- # How it works URL: https://www.screenlyyid.com/docs/getting-started/how-it-works/ > The three steps of a full ScreenlyyID onboarding integration: create an instance, collect images, then retrieve results. Canonical URL: https://www.screenlyyid.com/docs/getting-started/how-it-works/ A full onboarding integration with a mobile or web application has three steps. 1. **Create a session.** Call the [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/). It returns a correlation ID, which acts as your session token. 2. **Collect the ID and selfie images.** Choose how: the [mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/) WebView, the [web app](https://www.screenlyyid.com/docs/integrations/web-app/) integration, or a [custom integration](https://www.screenlyyid.com/docs/integrations/custom-integration/). 3. **Retrieve the results.** Optionally fetch the OCR data and decision results in real time, to make decisions in your app or save them to your own database. See [Data retrieval](https://www.screenlyyid.com/docs/data/). Results are also always visible in the ScreenlyyID dashboard. ## What you pass on every call | Header | Value | |---|---| | `x-api-key` | Your API key from the dashboard. | | `x-correlation-id` | The correlation ID returned by the Instance API for this customer's session. | See [Authentication](https://www.screenlyyid.com/docs/authentication/) for details. --- # Mobile app URL: https://www.screenlyyid.com/docs/integrations/mobile-app/ > Hand document and selfie capture to ScreenlyyID from a WebView inside your own mobile app. Canonical URL: https://www.screenlyyid.com/docs/integrations/mobile-app/ The mobile integration is customisable and works on any mobile platform with only a few lines of code. It uses a WebView to hand off document and selfie capture to ScreenlyyID from inside your app, so you only show the screens you need and users never leave your app. For the step-by-step version written for coding agents, with code for iOS, Android, React Native and Flutter, see [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/). Follow the implementation steps below, and see the [iOS sample app](https://github.com/ScreenlyyID/ios-sdk-example) and its example back end. It is written for iOS, but the concept works on any platform. Its README describes the same four steps. ## Camera permissions The capture page uses the device camera, and the WebView only gets it if your app has it. Ask for permission **before** you load the page, and handle a refusal in your own screen, because the page cannot recover from a denied camera. **iOS** (from the [iOS sample app](https://github.com/ScreenlyyID/ios-sdk-example), which sets all of this): - Add `NSCameraUsageDescription` to `Info.plist`, with text that tells the user why you need the camera. The sample also sets `NSMicrophoneUsageDescription`. - Call `AVCaptureDevice.authorizationStatus(for: .video)`. When it is `.notDetermined`, call `AVCaptureDevice.requestAccess(for: .video)` and load the page only if the user allows it. When it is `.denied` or `.restricted`, do not load the page: explain why the camera is needed and offer to open Settings. - Create the `WKWebView` with `allowsInlineMediaPlayback = true` so the camera preview plays inside the page. - Test on a real device. The iOS simulator has no camera. **Android** (there is no ScreenlyyID Android sample app yet; these are the usual Android WebView requirements): - Declare `android.permission.CAMERA` in the manifest and request it at runtime before you load the page. - Enable JavaScript in the WebView settings, and set a `WebChromeClient` whose `onPermissionRequest` grants the page's camera request once your app has the permission. **Browsers (iframe):** see [Web app](https://www.screenlyyid.com/docs/integrations/web-app/). ## Implementation steps ### Step 1: Create an instance Call the [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) **from your back end**, so your API key never ships inside the app. The response is `200` with two properties, spelled exactly like this: ```json { "CorrelationId": "6a0e5cb3-900c-41ca-ba84-08a08c6edff6", "webEnrolmentUrl": "https://app.screenlyyid.com/idv/6a0e5cb3-900c-41ca-ba84-08a08c6edff6" } ``` Keep the `CorrelationId` on your back end: you need it in [Step 4](https://www.screenlyyid.com/docs/integrations/mobile-app/#step-4). Pass only the `webEnrolmentUrl` to the app. The [iOS sample app](https://github.com/ScreenlyyID/ios-sdk-example) shows this split: its `backend/` folder is a small server that holds the API key and the `CorrelationId` and makes every ScreenlyyID call, and the app talks only to that server. ### Step 2: Open a WebView Start a WebView in your app and load the `webEnrolmentUrl` returned by the Instance API. It looks like this: ```text https://app.screenlyyid.com/idv/6a0e5cb3-900c-41ca-ba84-08a08c6edff6 ``` This starts the ScreenlyyID document enrolment process. The page photographs the ID document and takes a selfie, so the WebView needs camera access: see [Camera permissions](https://www.screenlyyid.com/docs/integrations/mobile-app/#camera-permissions) before you load it. #### The skipIntro parameter Add `skipIntro=true` to the URL to skip the intro screen and go straight to image capture: ```text https://app.screenlyyid.com/idv/6a0e5cb3-900c-41ca-ba84-08a08c6edff6?skipIntro=true ``` ### Step 3: Listen for events Listen for `postMessage` events from the page and act on them. The hosted page sends each event with `window.parent.postMessage`, so inside a WebView there is no outer page to receive it: you have to forward the page's `message` events to your app yourself. In the iOS sample app a `WKUserScript` adds `window.addEventListener('message', ...)` and passes each event to a `WKScriptMessageHandler`. Events use this format: ```json { "eventName": "", "isError": false, "error": "" } ``` The current events are: | Event | Meaning | |---|---| | `IDV_SESSION_COMPLETE` | Fired when the identity document and selfie have been processed and the results are stored. You can fetch the result from your back end straight away: no polling is needed. | | `ERROR` | A fatal, non-recoverable error occurred while processing the images (`isError` is `true` and `error` describes it). The SDK handles most errors itself, but you may want to listen for this event and restart the process or continue your onboarding flow. | If you only use the hosted document capture for identity verification (document collection, face match and liveness), it is safe to close the WebView and continue your app flow once `IDV_SESSION_COMPLETE` is received. ### Step 4: Get the results from your back end When your app receives `IDV_SESSION_COMPLETE`, call these two APIs **from your back end**, not from the app, so your API key stays secret. Send your `x-api-key`, and the `x-correlation-id` you got from the Instance API in [Step 1](https://www.screenlyyid.com/docs/integrations/mobile-app/#step-1): 1. [Get hosted SDK document data](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-document-data/) (`GET /api/v1/document/data`) returns the ID data read from the document (OCR and MRZ fields). 2. [Get hosted SDK decision result](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/) (`GET /api/v1/document/result`) returns the overall decision result for the scan, including the document checks, liveness and face match. For more on interpreting the results, see [Data retrieval](https://www.screenlyyid.com/docs/data/) and [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/). You can also review every verification in the dashboard: sign in and open **Verifications**. --- # Web app URL: https://www.screenlyyid.com/docs/integrations/web-app/ > Web app integration guidance for ScreenlyyID. Canonical URL: https://www.screenlyyid.com/docs/integrations/web-app/ To keep people inside your web app, embed the hosted capture page in an `iframe`. The page reports its result to the window that embeds it, so an iframe is what lets your app know the capture is finished. For the step-by-step version written for coding agents, see [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/). The flow is the same as for the [mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/): your server creates a session, the page captures the ID document and a selfie, and your server reads the result. ## 1. Create a session on your server Call the [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/) from your **server**, never from the browser, because the request carries your API key. Keep the `CorrelationId` from the response on your server and send only the `webEnrolmentUrl` to the browser. ## 2. Embed the page ```html ``` The `allow="camera; microphone"` attribute is needed because the page is on a different origin from yours: without it the browser does not let the embedded page use the camera. Your page must be served over HTTPS. Add `?skipIntro=true` to the URL to go straight to image capture. ## 3. Listen for events The hosted page tells its parent window when it is done, with `window.parent.postMessage`. The message is an object with `eventName`, `isError` and `error`: | Event | Meaning | |---|---| | `IDV_SESSION_COMPLETE` | The document and selfie have been collected. Hide the iframe and continue. | | `ERROR` | A fatal error occurred while processing the images (`isError` is `true`, `error` describes it). Offer to try again. | ```javascript window.addEventListener("message", (event) => { // The hosted page sends its messages to any origin, so check who sent this one. const frame = document.getElementById("screenlyyid"); if (event.source !== frame.contentWindow) return; if (event.origin !== new URL(frame.src).origin) return; const { eventName, isError, error } = event.data || {}; if (eventName === "IDV_SESSION_COMPLETE" && !isError) { frame.remove(); // tell your server to fetch the result (step 4), then continue } else if (eventName === "ERROR") { console.error("Verification failed:", error); } }); ``` Treat the event only as a signal to carry on. Do not trust the browser for the outcome: your server must read the decision itself. ## Continue on a phone On a desktop browser the embedded page shows a QR code first. The person scans it, captures their ID document and selfie on their phone, and your page receives the same `IDV_SESSION_COMPLETE` or `ERROR` message when the phone finishes. Add `handoff=off` to the URL to skip the QR code and capture on the desktop. See the [web identity verification guide](https://www.screenlyyid.com/docs/guides/identity-verification-web/#handoff). ## 4. Get the result from your server When the event arrives, your server calls [Get hosted SDK document data](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-document-data/) (`GET /api/v1/document/data`) and [Get hosted SDK decision result](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/) (`GET /api/v1/document/result`) with the headers `x-api-key` and `x-correlation-id`. The hosted page sends `IDV_SESSION_COMPLETE` only after it has processed the document and selfie and the results are stored, so one call is enough: you do not need to poll. (Called before that event, these endpoints return an error: HTTP 500 with `{"error":"internal_error"}`.) See the [AI quickstart](https://www.screenlyyid.com/docs/ai-quickstart/) for code. You can also build your own capture screens: see the [custom integration](https://www.screenlyyid.com/docs/integrations/custom-integration/) with the [JavaScript (Vue) SDK](https://github.com/ScreenlyyID/javascript-vue-sdk), or send customers a [no-code link](https://www.screenlyyid.com/docs/getting-started/integration-options/#no-code-links). --- # Custom integration URL: https://www.screenlyyid.com/docs/integrations/custom-integration/ > Build your own image capture and use the ScreenlyyID APIs to authenticate and analyse the images. Canonical URL: https://www.screenlyyid.com/docs/integrations/custom-integration/ You can implement your own image capture system and use the ScreenlyyID APIs to identify and analyse the images. 1. Check out the [demo app](https://github.com/ScreenlyyID/javascript-vue-sdk). It is a full working example of the APIs and the data they require for a custom integration. 2. Read about the APIs in [Identity verification](https://www.screenlyyid.com/docs/api-reference/identity-verification/), which lists the calls in order. --- # Recipes URL: https://www.screenlyyid.com/docs/recipes/ > Working examples for adding ScreenlyyID identity verification to common stacks: Express, FastAPI, Next.js and iOS. Canonical URL: https://www.screenlyyid.com/docs/recipes/ Working examples for common stacks. They all follow the same shape, taken from the [AI quickstart](https://www.screenlyyid.com/docs/ai-quickstart/) and the [Mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/) guide: 1. **Your server** creates a verification session with your API key and keeps the `CorrelationId`. 2. **The person** is sent to the hosted capture page (in an iframe, a browser tab or a mobile WebView). The page asks for the camera. 3. The page sends **`IDV_SESSION_COMPLETE`** when the capture has been processed and the results are stored. 4. **Your server** reads the result once with the `CorrelationId`. The API key never goes into a browser or an app. | Recipe | For | |---|---| | [Express (Node.js)](https://www.screenlyyid.com/docs/recipes/express/) | A Node back end | | [FastAPI (Python)](https://www.screenlyyid.com/docs/recipes/fastapi/) | A Python back end | | [Next.js](https://www.screenlyyid.com/docs/recipes/nextjs/) | A full-stack web app (route handlers and an iframe page) | | [iOS (Swift)](https://www.screenlyyid.com/docs/recipes/ios/) | A native iPhone app, with its own back end | All the code is also in the public [ScreenlyyID/examples](https://github.com/ScreenlyyID/examples) repo, ready to clone and run. Every ScreenlyyID call is a plain REST request, so any language with an HTTP client works: there is no SDK package to install. Using a coding agent? Give it the [AI quickstart](https://www.screenlyyid.com/docs/ai-quickstart/) prompt, or install the [ScreenlyyID agent skill](https://www.screenlyyid.com/docs/agent-skills/). --- # Express (Node.js) URL: https://www.screenlyyid.com/docs/recipes/express/ > Add ScreenlyyID identity verification to an Express back end: create a session, then read the result after the hosted page reports it is done. Canonical URL: https://www.screenlyyid.com/docs/recipes/express/ An Express server with the two routes a ScreenlyyID integration needs. The API key and the `CorrelationId` stay on the server; your front end only receives a `verificationId` and the hosted page URL. Node 18 or later. | Route | What it does | |---|---| | `POST /api/verifications` | Step 1: calls [`instance/create`](https://www.screenlyyid.com/docs/authentication/create-instance/) and returns `{ verificationId, webEnrolmentUrl }`. | | `GET /api/verifications/:id` | Step 4: after the front end receives `IDV_SESSION_COMPLETE`, reads the result once with [`document/result`](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/). | ## Install ```bash npm install express ``` Create a test key (see [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key)) and put it in your environment: ```bash export SCREENLYYID_API_KEY=test_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ``` ## server.js Add `"type": "module"` to `package.json`. ```javascript // Express back end for ScreenlyyID identity verification. Node 18 or later. // The API key and the CorrelationId stay on this server: the browser only gets a verificationId and the hosted page URL. import express from "express"; import { randomUUID } from "node:crypto"; const API = "https://api.screenlyyid.com"; const apiKey = process.env.SCREENLYYID_API_KEY; // a test_ key while you build if (!apiKey) throw new Error("SCREENLYYID_API_KEY is not set"); // verificationId -> { userId, correlationId }. In memory for the example; use your database. const sessions = new Map(); const app = express(); app.use(express.json()); // Step 1: create a verification session (server side). app.post("/api/verifications", async (req, res) => { const userId = req.user?.id ?? "demo-user"; // replace with your own authentication const r = await fetch(`${API}/api/v1/instance/create`, { method: "POST", headers: { "x-api-key": apiKey, "Content-Type": "application/json" }, body: JSON.stringify({ GlobalScreening: ["idv"], CustomerIntelligence: [] }), }); if (!r.ok) return res.status(502).json({ error: `ScreenlyyID instance/create failed (HTTP ${r.status})` }); const { CorrelationId, webEnrolmentUrl } = await r.json(); // the property names are exactly these const verificationId = randomUUID(); sessions.set(verificationId, { userId, correlationId: CorrelationId }); res.status(201).json({ verificationId, webEnrolmentUrl }); // the CorrelationId is not sent to the browser }); // Step 4: after the browser reports IDV_SESSION_COMPLETE, read the result once. app.get("/api/verifications/:id", async (req, res) => { const session = sessions.get(req.params.id); if (!session || session.userId !== (req.user?.id ?? "demo-user")) return res.status(404).json({ error: "Unknown verification" }); const r = await fetch(`${API}/api/v1/document/result`, { headers: { "x-api-key": apiKey, "x-correlation-id": session.correlationId }, }); if (r.status === 200) return res.json({ status: "ready", result: await r.json() }); if (r.status === 500) return res.json({ status: "pending" }); // asked before the capture finished res.status(502).json({ error: `ScreenlyyID document/result failed (HTTP ${r.status})` }); }); app.listen(process.env.PORT || 3000, () => console.log("listening")); ``` ## Run and test ```bash node server.js ``` ```bash curl -s -X POST localhost:3000/api/verifications # {"verificationId":"...","webEnrolmentUrl":"https://app.screenlyyid.com/idv/..."} curl -s localhost:3000/api/verifications/VERIFICATION_ID # {"status":"pending"} (asked before the person has finished the capture) ``` Open `webEnrolmentUrl` in a browser or embed it as described in [Web app](https://www.screenlyyid.com/docs/integrations/web-app/). When the page reports `IDV_SESSION_COMPLETE`, the same `GET` returns `{"status":"ready","result":{...}}`. The front end is the same as for any web app: embed `webEnrolmentUrl` in an iframe with `allow="camera; microphone"`, listen for the event, then call your `GET` route. See [Web app](https://www.screenlyyid.com/docs/integrations/web-app/) and the [Next.js recipe](https://www.screenlyyid.com/docs/recipes/nextjs/) for a complete page. **Run it from the repo:** this is the code in [`express/`](https://github.com/ScreenlyyID/examples/tree/main/express) of the public examples repo ([ScreenlyyID/examples](https://github.com/ScreenlyyID/examples)), which has a README and an `.env.example`. ## What this does not include - **Your own sign-in.** The sample uses a fixed `demo-user`. Replace it with your authentication, and keep the check that a verification belongs to the person asking. - **A database.** Sessions are kept in memory so the sample stays short. Store the `CorrelationId` against your user in your database. - **HTTPS and rate limits.** Add both before this faces the internet. See the [AI quickstart](https://www.screenlyyid.com/docs/ai-quickstart/) for the full API flow and the [error table](https://www.screenlyyid.com/docs/ai-quickstart/#errors). --- # FastAPI (Python) URL: https://www.screenlyyid.com/docs/recipes/fastapi/ > Add ScreenlyyID identity verification to a FastAPI back end: create a session, then read the result after the hosted page reports it is done. Canonical URL: https://www.screenlyyid.com/docs/recipes/fastapi/ A FastAPI app with the two routes a ScreenlyyID integration needs. The API key and the `CorrelationId` stay on the server; your front end or app only receives a `verificationId` and the hosted page URL. Python 3.9 or later. | Route | What it does | |---|---| | `POST /api/verifications` | Step 1: calls [`instance/create`](https://www.screenlyyid.com/docs/authentication/create-instance/) and returns `{ verificationId, webEnrolmentUrl }`. | | `GET /api/verifications/{id}` | Step 4: after the front end receives `IDV_SESSION_COMPLETE`, reads the result once with [`document/result`](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/). | ## Install ```bash pip install fastapi uvicorn httpx export SCREENLYYID_API_KEY=test_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ``` Create a test key first: see [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key). ## main.py ```python """FastAPI back end for ScreenlyyID identity verification. Python 3.9 or later. The API key and the CorrelationId stay on this server: the browser or app only gets a verification_id and the hosted page URL. Run: SCREENLYYID_API_KEY=test_... uvicorn main:app """ import os import uuid import httpx from fastapi import FastAPI, HTTPException API = "https://api.screenlyyid.com" API_KEY = os.environ["SCREENLYYID_API_KEY"] # a test_ key while you build app = FastAPI() # verification_id -> {"user_id": ..., "correlation_id": ...}. In memory for the example; use your database. sessions: dict = {} def current_user_id() -> str: return "demo-user" # replace with your own authentication @app.post("/api/verifications", status_code=201) async def create_verification(): """Step 1: create a verification session (server side).""" async with httpx.AsyncClient(timeout=30) as client: r = await client.post( f"{API}/api/v1/instance/create", headers={"x-api-key": API_KEY}, json={"GlobalScreening": ["idv"], "CustomerIntelligence": []}, ) if r.status_code != 200: raise HTTPException(502, f"ScreenlyyID instance/create failed (HTTP {r.status_code})") body = r.json() # the property names are exactly CorrelationId and webEnrolmentUrl verification_id = str(uuid.uuid4()) sessions[verification_id] = {"user_id": current_user_id(), "correlation_id": body["CorrelationId"]} return {"verificationId": verification_id, "webEnrolmentUrl": body["webEnrolmentUrl"]} # no CorrelationId @app.get("/api/verifications/{verification_id}") async def get_verification(verification_id: str): """Step 4: after the browser or app reports IDV_SESSION_COMPLETE, read the result once.""" session = sessions.get(verification_id) if not session or session["user_id"] != current_user_id(): raise HTTPException(404, "Unknown verification") async with httpx.AsyncClient(timeout=30) as client: r = await client.get( f"{API}/api/v1/document/result", headers={"x-api-key": API_KEY, "x-correlation-id": session["correlation_id"]}, ) if r.status_code == 200: return {"status": "ready", "result": r.json()} if r.status_code == 500: # asked before the capture finished return {"status": "pending"} raise HTTPException(502, f"ScreenlyyID document/result failed (HTTP {r.status_code})") ``` ## Run and test ```bash uvicorn main:app --port 3000 ``` ```bash curl -s -X POST localhost:3000/api/verifications # {"verificationId":"...","webEnrolmentUrl":"https://app.screenlyyid.com/idv/..."} curl -s localhost:3000/api/verifications/VERIFICATION_ID # {"status":"pending"} (asked before the person has finished the capture) ``` Open `webEnrolmentUrl` in a browser or embed it as described in [Web app](https://www.screenlyyid.com/docs/integrations/web-app/). When the page reports `IDV_SESSION_COMPLETE`, the same `GET` returns `{"status":"ready","result":{...}}`. The front end is the same as for any web app: embed `webEnrolmentUrl` in an iframe with `allow="camera; microphone"`, listen for the event, then call your `GET` route. See [Web app](https://www.screenlyyid.com/docs/integrations/web-app/). For a mobile app, see the [iOS recipe](https://www.screenlyyid.com/docs/recipes/ios/). **Run it from the repo:** this is the code in [`fastapi/`](https://github.com/ScreenlyyID/examples/tree/main/fastapi) of the public examples repo ([ScreenlyyID/examples](https://github.com/ScreenlyyID/examples)), which has a README and an `.env.example`. ## What this does not include - **Your own sign-in.** The sample uses a fixed `demo-user`. Replace it with your authentication, and keep the check that a verification belongs to the person asking. - **A database.** Sessions are kept in memory so the sample stays short. Store the `CorrelationId` against your user in your database. - **HTTPS and rate limits.** Add both before this faces the internet. See the [AI quickstart](https://www.screenlyyid.com/docs/ai-quickstart/) for the full API flow and the [error table](https://www.screenlyyid.com/docs/ai-quickstart/#errors). --- # Next.js URL: https://www.screenlyyid.com/docs/recipes/nextjs/ > Add ScreenlyyID identity verification to a Next.js app: two route handlers on the server and a page that embeds the hosted capture page. Canonical URL: https://www.screenlyyid.com/docs/recipes/nextjs/ A Next.js (App Router) app with two server route handlers and a page that embeds the hosted capture page. The API key and the `CorrelationId` stay on the server. Shown with Next.js 14. | File | What it does | |---|---| | `lib/screenlyyid.js` | Server-only helpers: the two ScreenlyyID calls and the in-memory session store. | | `app/api/verifications/route.js` | `POST`: Step 1, calls [`instance/create`](https://www.screenlyyid.com/docs/authentication/create-instance/). | | `app/api/verifications/[id]/route.js` | `GET`: Step 4, reads the result once with [`document/result`](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/). | | `app/page.js` | The page: starts a verification, embeds the hosted page in an iframe, listens for `IDV_SESSION_COMPLETE`. | ## Setup Add a path alias for `@/` in `jsconfig.json`, and put a test key in `.env.local` (never commit it). See [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key). ```json { "compilerOptions": { "paths": { "@/*": ["./*"] } } } ``` ```bash # .env.local SCREENLYYID_API_KEY=test_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ``` ## lib/screenlyyid.js ```javascript // Server-only helpers. The API key and the CorrelationId never reach the browser. const API = "https://api.screenlyyid.com"; // verificationId -> { userId, correlationId }. In memory for the example; use your database. // (A module-level Map is shared per server process; with several instances or serverless functions, use a database.) const globalStore = globalThis; export const sessions = (globalStore.__sessions ??= new Map()); export function apiKey() { const key = process.env.SCREENLYYID_API_KEY; // a test_ key while you build if (!key) throw new Error("SCREENLYYID_API_KEY is not set"); return key; } 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: ["idv"], CustomerIntelligence: [] }), cache: "no-store", }); if (!r.ok) throw new Error(`ScreenlyyID instance/create failed (HTTP ${r.status})`); return r.json(); // { CorrelationId, webEnrolmentUrl }: the property names are exactly these } export function getResult(correlationId) { return fetch(`${API}/api/v1/document/result`, { headers: { "x-api-key": apiKey(), "x-correlation-id": correlationId }, cache: "no-store", }); } ``` ## app/api/verifications/route.js ```javascript import { randomUUID } from "node:crypto"; import { createInstance, sessions } from "@/lib/screenlyyid"; export const dynamic = "force-dynamic"; // Step 1: create a verification session (server side). export async function POST() { const userId = "demo-user"; // replace with your own authentication try { const { CorrelationId, webEnrolmentUrl } = await createInstance(); const verificationId = randomUUID(); sessions.set(verificationId, { userId, correlationId: CorrelationId }); return Response.json({ verificationId, webEnrolmentUrl }, { status: 201 }); // no CorrelationId } catch (e) { return Response.json({ error: e.message }, { status: 502 }); } } ``` ## app/api/verifications/[id]/route.js ```javascript import { getResult, sessions } from "@/lib/screenlyyid"; export const dynamic = "force-dynamic"; // Step 4: after the browser reports IDV_SESSION_COMPLETE, read the result once. export async function GET(_request, { params }) { const userId = "demo-user"; // replace with your own authentication const session = sessions.get(params.id); if (!session || session.userId !== userId) return Response.json({ error: "Unknown verification" }, { status: 404 }); const r = await getResult(session.correlationId); if (r.status === 200) return Response.json({ status: "ready", result: await r.json() }); if (r.status === 500) return Response.json({ status: "pending" }); // asked before the capture finished return Response.json({ error: `ScreenlyyID document/result failed (HTTP ${r.status})` }, { status: 502 }); } ``` ## app/page.js ```javascript "use client"; import { useEffect, useRef, useState } from "react"; export default function Page() { const [session, setSession] = useState(null); // { verificationId, webEnrolmentUrl } const [message, setMessage] = useState(""); const frame = useRef(null); async function start() { const r = await fetch("/api/verifications", { method: "POST" }); const body = await r.json(); if (!r.ok) return setMessage(body.error); setSession(body); } // Step 3: the hosted page tells its parent window when it is done. useEffect(() => { if (!session) return; async function onMessage(event) { const el = frame.current; if (!el || event.source !== el.contentWindow) return; // only the iframe we created if (event.origin !== new URL(el.src).origin) return; // and only from the hosted page's origin const { eventName, isError, error } = event.data || {}; if (eventName === "IDV_SESSION_COMPLETE" && !isError) { // Step 4: ask YOUR server for the result. It reads it from ScreenlyyID once. const r = await fetch(`/api/verifications/${session.verificationId}`); setMessage(JSON.stringify(await r.json())); setSession(null); } else if (eventName === "ERROR") { setMessage("Verification failed: " + error); setSession(null); } } window.addEventListener("message", onMessage); return () => window.removeEventListener("message", onMessage); }, [session]); return (
{session && (