ScreenlyyIDDocs
Docs › Guides

Add electronic identity verification (eIDV) to your app

View as Markdown

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:

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.
  • 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.
  • 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).
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 '{"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#

  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: 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"
  }
}
FieldTypeMeaningExample
IdentityobjectCompletename, Givenfullname, SurnameFirst, Nationalid, Dob.{ "Completename": "Jane Citizen" }
AddressobjectAddressLine1, AddressLine2, HouseNumber, HouseNumberAddition, Thoroughfare, Locality, PostalCode, Province, CountryCode.{ "CountryCode": "AU" }
PhoneobjectPhoneNumber.{ "PhoneNumber": "+61..." }
EmailobjectFullEmailAddress.{ "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": "..."
  }
}
FieldTypeMeaningExample
Codes.Reliabilitystring★ How reliable the match is.
Codes.DetailCodestring★ The detail code for the match.
Codes.CodesDetailListstring★ Detailed per-field result codes.
Codes.AdaptationstringAdaptation code.
Identity / Address / Phone / EmailobjectThe 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.
  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 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#

StatusWhenBody
400A required field is missing or the body is not valid JSONA problem-details object: {"type": "...", "title": "One or more validation errors occurred.", "status": 400, "errors": {"<Field>": ["The <Field> field is required."]}}
401x-api-key is missing or malformed, or the product is not activated on the accountEmpty body with a WWW-Authenticate header
409The same x-correlation-id was already used for this product{"error": "duplicate_correlation_id", "message": "Duplicate correlation id received."}
500The 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.

InputExpected result
a person that exists in the data sources200 with Codes (Reliability, DetailCode, CodesDetailList) and the matched Identity, Address, Phone and Email sections.
a person that does not exist200 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