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, 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 has an "I want to..." table:
| I want to... | Guide |
|---|---|
| Verify ID document and selfie in a mobile app | Identity verification (mobile) |
| Verify ID document and selfie in a web app | Identity verification (web) |
| Check a card at checkout | BIN lookup |
| Validate phone numbers or emails at sign-up | Phone, Email |
| Check addresses, IPs and devices | Address, Device and IP |
| Verify a person without a document, or screen for sanctions | eIDV, AML screening |
| Run several checks for one customer | Run several checks in one session |
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.
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-keyheader on every request. - Session token: a
CorrelationIdthat you get from the create-instance call and send in thex-correlation-idheader 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. - 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.
- Register at admin.screenlyyid.com/register and choose the Free plan, then verify your email and complete your company details. See Signing up.
- In the dashboard open Integrations and create an API key. Choose the test (sandbox) environment. Test keys start with
test_; production keys start withprod_. - Put the key in your environment, for example in a
.envfile that is not committed:
SCREENLYYID_API_KEY=test_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx1. Create a verification session (server side)#
Call the Instance API.
curl --request POST \
--url 'https://api.screenlyyid.com/api/v1/instance/create' \
--header "x-api-key: $SCREENLYYID_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"FirstName": "Jane",
"LastName": "Citizen",
"GlobalScreening": ["idv"],
"CustomerIntelligence": []
}'A successful response is 200 with these two properties, spelled exactly like this:
{
"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):
// 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):
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) 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. 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 for the full WebView steps and the iOS example app.
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:
GET /api/v1/document/datareturns the data read from the document (OCR and MRZ). - Get hosted SDK decision result:
GET /api/v1/document/resultreturns the decision, with the document checks, liveness and face match.
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:
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:
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 NoneCall 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 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 and 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-keyon the server and never in client code. - End to end: use a
test_key, create a session, openwebEnrolmentUrl, complete the capture, then callGET /api/v1/document/resultwith the storedCorrelationId. - Debugging: every request is listed under Logs in the dashboard, searchable by transaction ID.
Go live#
- 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. - Set
SCREENLYYID_API_KEYto the production key in your production environment only. - Nothing else changes: the base URL is the same.
More for agents#
- Working examples (Express, FastAPI, Next.js, iOS): Recipes
- Install the agent skill: Agent skills
- All developer docs as one Markdown file: /docs/llms-full.txt
- OpenAPI spec: /openapi.json
- API catalog: /.well-known/api-catalog
- Site index for language models: /llms.txt