# 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)
