# Add electronic identity verification (eIDV) to your app

> Add electronic identity verification (eIDV) with ScreenlyyID: the instance call, the request, the response fields, the decision rule, working Node, Python and Next.js code, and a checklist.

Canonical URL: https://www.screenlyyid.com/docs/guides/electronic-identity-verification/

## 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:**

- 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)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) and [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/). Do not use the direct identity verification endpoints.
- You only need to check an address format: [Address verification](https://www.screenlyyid.com/docs/guides/address-verification/).

## 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](https://www.screenlyyid.com/docs/ai-quickstart/#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](https://www.screenlyyid.com/pricing/).
- **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).

```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 '{"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](https://www.screenlyyid.com/docs/guides/stacking-checks/). 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](https://www.screenlyyid.com/docs/guides/electronic-identity-verification/#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"
  }
}
```

| 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
```json
{
  "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

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](https://www.screenlyyid.com/docs/api-reference/electronic-identity-verification/).
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](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) 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

| 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)
```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.

| 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 `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

## Related

- [Electronic identity verification (API reference)](https://www.screenlyyid.com/docs/api-reference/electronic-identity-verification/)
- [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/)
- [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/)
