Add electronic identity verification (eIDV) to your app
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 enougheid-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) and Identity verification (web). Do not use the direct identity verification endpoints.
- You only need to check an address format: Address verification.
Before you start#
- API key: read it from the environment variable
SCREENLYYID_API_KEYon your server only. Use atest_key for the sandbox and aprod_key for live. Never put it in browser or mobile code. See Get a test key. - Base URL:
https://api.screenlyyid.com. HTTPS only. - Activation and plan: The product must be activated on the account:
eidv1for 1x1 andeidv2for 2x2. They are listed inGlobalScreeningin the instance call. eIDV is billed per check: see the pricing page. - Start with the Instance API. Every flow starts with
POST /api/v1/instance/create, listing this product's code (eidv1) inGlobalScreening. It returns aCorrelationIdthat you send asx-correlation-idon the product call, along withx-api-key. A product call can be accepted only once per correlation id: repeating it with the same id can return409 duplicate_correlation_id. Create a new instance for each check (for example one per checkout or per sign-up).
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. 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#
- Create the instance in your server code, right before the check. Keep the
CorrelationIdwith your own record (the user, the order). Do this on the server. - Call the endpoint
POST /api/v1/eid-validate-1x1withx-api-key,x-correlation-idand a JSON body (next section). In a typical app this is the sign-up or form-submit handler, before you create the account. - Read the response and apply the decision logic: the fields marked ★ are the ones to base a decision on.
- Act on the result: accept, ask the customer to correct their input, flag for review, or block. Store the
CorrelationIdand the outcome: it is your audit trail, and the same id shows the check in the dashboard. - Handle failures (below) so a provider outage never breaks your flow.
Request and response#
Request#
{
"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#
{
"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#
- 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. - Choose 1x1 or 2x2 by the assurance you need. Use 2x2 when you need two independent sources to agree.
- A non-match is not proof of fraud: send the person to the hosted identity verification or to manual review.
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": {"<Field>": ["The <Field> 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)#
// 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)#
# 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#
// 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
eidv1oreidv2inGlobalScreeningand theCorrelationIdis sent asx-correlation-id - [ ] The right endpoint is called for the product listed (1x1 for
eidv1, 2x2 foreidv2) - [ ] 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
200with atest_key