eID verification

Verify a customer's age with their Icelandic electronic ID. Start a request, show the returned code to the customer, and poll until they have confirmed in their eID app or on their phone's SIM.

Step 1: start the request

curl -X POST https://abyrgverslun.is/api/v1/verifications \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "eid",
    "loginType": "sim",
    "identifier": "7771234",
    "requiredAge": 20,
    "posReference": "till4-1234"
  }'

{
  "id": "kcb4mk3xdgmxdndafcjn7k50xweckqrb",
  "status": "pending",
  "authId": "<the eID Provider's reference>",
  "code": "4821",
  "livemode": true
}

id is what you poll. code is shown to the customer. authId is the eID Provider's own reference for the sign-in; you don't need it to poll.

Identifier format

identifier is an Icelandic phone number or a kennitala. Read on its digits only, it must be one of:

• A phone number: exactly 7 digits, optionally after the country code 354, 00354 or +354. Foreign numbers are refused.
• A kennitala: exactly 10 digits with a valid check digit.

Send it as typed or pasted; formatting is allowed, as long as it follows these rules:

• Digits are ASCII 0 to 9 only. Fullwidth digits (８８８５００１) and Arabic-Indic digits (٨٨٨٥٠٠١) are refused.
• Separators: space, -, ., ( and ), anywhere.
• An optional + or (+ at the start, as in +354 888 5001 or (+354) 888 5001, only before 354. A + anywhere else, or before any other digits (+8885001), is refused.
• At most 20 characters, after leading and trailing spaces are trimmed.
• At most 256 characters as sent, before invisible characters are dropped.
• Invisible characters that copied numbers often carry are dropped before the check: text-direction marks (U+061C, U+200E, U+200F, U+202A to U+202E, U+2066 to U+2069), zero-width space, non-joiner and joiner (U+200B to U+200D) and word joiner (U+2060).
• Non-breaking and other Unicode spaces are read as a space, and Unicode dashes and the minus sign as -.

Any other character, such as / or ,, is refused. An identifier that breaks these rules gets 422 with type validation-error, and the customer is not prompted. For example, 888-5001, +354 888 5001, 3548885001, 003548885001, 010130-2989 and 010130.2989 are accepted; 12345678 (8 digits), 08885001, +8885001, +44 7911 123456, 1234567890 (bad check digit), 010130/2989, 888,5001 and 8885001+ are refused. The test eID identifiers are accepted too.

Step 2: poll for the result

curl https://abyrgverslun.is/api/v1/verifications/kcb4mk3xdgmxdndafcjn7k50xweckqrb \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const BASE = 'https://abyrgverslun.is';
const headers = {
  'Authorization': `Bearer ${accessToken}`,
  'Content-Type': 'application/json',
};

const start = await fetch(`${BASE}/api/v1/verifications`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    method: 'eid',
    loginType: 'sim',
    identifier: '7771234',
    requiredAge: 20,
  }),
});
if (!start.ok) throw new Error(`eID start failed: ${start.status}`);
const { id, code } = await start.json();

showCodeToCustomer(code);

const FINAL = ['success', 'rejected', 'timeout'];
let verification;
do {
  await new Promise((resolve) => setTimeout(resolve, 2500));
  const poll = await fetch(`${BASE}/api/v1/verifications/${id}`, { headers });
  if (!poll.ok) throw new Error(`eID poll failed: ${poll.status}`);
  verification = await poll.json();
} while (!FINAL.includes(verification.status));

if (verification.status === 'success' && verification.result === 'pass') {
  // Customer is at least requiredAge
} else {
  // Underage (success + fail), declined (rejected) or expired (timeout)
}

// Customer has not answered yet: keep polling
{ "id": "kcb4mk3xdgmxdndafcjn7k50xweckqrb", "status": "pending", "livemode": true }

// Customer signed in and meets requiredAge
{
  "id": "kcb4mk3xdgmxdndafcjn7k50xweckqrb",
  "status": "success",
  "result": "pass",
  "transactionId": "k1jcce4akgxtehpqa9pz2809dnxpxhfq",
  "livemode": true
}

// Customer signed in but is under requiredAge
{
  "id": "kcb4mk3xdgmxdndafcjn7k50xweckqrb",
  "status": "success",
  "result": "fail",
  "transactionId": "k1jcce4akgxtehpqa9pz2809dnxpxhfq",
  "livemode": true
}

// Customer declined, or the sign-in failed: no transaction
{ "id": "kcb4mk3xdgmxdndafcjn7k50xweckqrb", "status": "rejected", "livemode": true }

// First poll after the 5-minute expiry: no transaction
{ "id": "kcb4mk3xdgmxdndafcjn7k50xweckqrb", "status": "timeout", "livemode": true }

// A pass or manual verification, looked up by transactionId
{
  "id": "k1jcce4akgxtehpqa9pz2809dnxpxhfq",
  "status": "completed",
  "result": "pass",
  "transactionId": "k1jcce4akgxtehpqa9pz2809dnxpxhfq",
  "livemode": true
}

Statuses

Once an eID request has a final status, later polls answer from the stored result without contacting the eID Provider again. The one change is expiry: the first poll after it returns timeout, and every poll after that returns rejected.

Retrying safely

Starting a request prompts the customer's phone, so retrying a start whose response you lost would prompt them again. Send an Idempotency-Key header (a fresh UUID per verification) and reuse it on every retry of that start:

• A retry with the same key and the same body within 24 hours returns the original response (the same id and code) with the header Idempotent-Replayed: true. The phone is not prompted again. Poll the id for the current status.
• A retry sent while the first request is still being started gets 409 with type idempotency-key-in-flight and is not run. Wait a moment and retry with the same key.
• The same key with a different body gives 422 with type idempotency-key-reused.
• A start that failed (for example a 500 from the eID Provider, or a 400) is not stored: a retry with the same key runs again.
• Keys belong to the caller: your service client or device in your tenant. They work the same on a test tenant.

Errors

Both calls return Problem Details (application/problem+json). See Errors.

Changes

• 2026-10-14: identifier must be an Icelandic phone number or a kennitala (see Identifier format). 8–9 digit values, other lengths, a leading + without 354, and 10-digit values that fail the kennitala checksum are now refused with 400/422 before any eID prompt. Before, they were sent on to the eID Provider, which failed them after the customer had waited.
• 2026-10-12: Invisible characters in identifier are now removed instead of refused: the Arabic letter mark (U+061C), zero-width space, non-joiner and joiner (U+200B to U+200D) and word joiner (U+2060). A number pasted with any of them is accepted, so you don't need to strip them yourself.
• 2026-10-08: identifier must follow the Identifier format. Before, any 1 to 20 characters were sent on to the eID Provider. Now an identifier such as 010130/2989, 888,5001, one with a trailing + (8885001+), one with non-ASCII digits (８８８５００１), letters, or fewer than 7 digits is refused with 422 validation-error, and the customer is not prompted. Remove these characters before you send the identifier.