ScreenlyyIDDocs
Docs › Getting started

AI quickstart

View as Markdown

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 appIdentity verification (mobile)
Verify ID document and selfie in a web appIdentity verification (web)
Check a card at checkoutBIN lookup
Validate phone numbers or emails at sign-upPhone, Email
Check addresses, IPs and devicesAddress, Device and IP
Verify a person without a document, or screen for sanctionseIDV, AML screening
Run several checks for one customerRun 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-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.
  • 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 and choose the Free plan, then verify your email and complete your company details. See 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:
Shell
SCREENLYYID_API_KEY=test_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

1. Create a verification session (server side)#

Call the Instance API.

Shell
curl --request POST \
  --url 'https://api.screenlyyid.com/api/v1/instance/create' \
  --header "x-api-key: $SCREENLYYID_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "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) 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": "" }:

EventMeaning
IDV_SESSION_COMPLETEThe document and selfie have been collected. It is safe to close the WebView and continue your app.
ERRORA 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.

Shell
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 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.

StatusWhenBody
200SuccessThe result, or the session for create-instance.
400instance/create: a product code that does not exist or is not activated on your accountA 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.
400The result endpoints without an x-correlation-id header{"error": "correlation_id_required", "message": "No correlation id found."}
401x-api-key is missing or not validA problem-details object with "title": "Unauthorized" and "status": 401. Check that the key is complete, including its test_ or prod_ prefix.
500GET /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.
  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#