Verify identity with sajn ID
Send a BankID identity check to a person by email or SMS, and get the result by webhook
In this guide, you verify a person's identity with sajn ID. sajn sends the person a link by email or SMS, the person identifies with Swedish BankID, and you get the result. Use it before you grant access to a service, open an account, or send a contract.
sajn ID checks the identity in one of two ways:
- With a national identity number: when you send
nationalId, BankID checks that the person has that number. - With the name: without
nationalId, BankID checks that the person's name matchesfullName. Use this when you don't need the identity number.
Before you begin
- Store your API key in the
SAJN_API_KEYenvironment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys). - Subscribe a webhook endpoint to
identity_check.verified,identity_check.failed, andidentity_check.cancelled. For more information, see Webhooks. - Each check counts toward your organization's monthly identity check quota.
Run an identity check
Create the check
Send a POST request to /api/v1/identity-checks. Creating the check also sends it, so there's no separate send step:
curl -X POST https://app.sajn.se/api/v1/identity-checks \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"fullName": "Alex Andersson",
"channel": "EMAIL",
"email": "alex@example.com",
"reference": "signup-4711",
"language": "en"
}'The request takes the following fields:
fullNameandchannelare required. With"channel": "SMS", sendphoneinstead ofemail.nationalIdmakes BankID check the identity number.referenceis your own ID for the check, returned in the check and its webhook events.contactIdlinks the check to a contact.languageis the language of the messages, as an ISO 639-1 code such asen. The default issv.expiresAtis when the link stops working. The default is seven days after creation.
The response is the check. Store its id. Only this response has verificationUrl, in case you want to show the link yourself:
{
"id": "cm4k2xm3a0012abcd7913wxyz",
"organizationId": "cm4k2xz0a0000abcd0000orgx",
"fullName": "Alex Andersson",
"email": "alex@example.com",
"phone": null,
"channel": "EMAIL",
"status": "SENT",
"reference": "signup-4711",
"language": "en",
"expiresAt": "2026-10-08T09:00:00.000Z",
"verifiedAt": null,
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z",
"verificationUrl": "https://id.sajn.se/v/R4nd0mT0k3n",
"contact": null,
"createdBy": { "id": "cm4k2xw3c0000abcd0000usrx", "email": "dana@example.com", "name": "Dana Lund" },
"audits": null,
"data": null
}Get the result
When the person finishes, sajn sends an identity_check.verified event. A failed or cancelled check sends identity_check.failed or identity_check.cancelled, and identity_check.failed adds the reason in data.failureReason. The event's data.object is the check, so find your record by its reference:
// Inside your webhook handler, after you verify the signature.
const check = event.data.object;
if (event.type === "identity_check.verified") {
await markVerified(check.reference, check.verifiedAt);
}
if (event.type === "identity_check.failed") {
await markFailed(check.reference, event.data.failureReason);
}markVerified and markFailed stand for your own code. To verify the signature, see Verify webhook signatures. For the full event, see Webhook payloads.
Don't poll the check to wait for the result. A check stays open until the person identifies or the link expires, by default seven days after creation. If sajn can't reach your server, read GET /api/v1/events on a schedule with type=identity_check.verified,identity_check.failed,identity_check.cancelled, and pass each event to the same handler. One request returns every check that ended since your last run. For the loop, see Reconcile on a schedule. A check that expires sends no event, so treat a check that's still open after its expiresAt as expired.
To read one check, such as when your user opens their application, get it by ID:
curl https://app.sajn.se/api/v1/identity-checks/CHECK_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"Replace CHECK_ID with the check id. status moves through CREATED, SENT, OPENED, and ends at VERIFIED, FAILED, EXPIRED, or CANCELLED. A verified check also has verifiedAt, the BankID result in data, and its event history in audits.
The BankID result in data contains personal data, such as the identity number. Store only what you need.
List checks
GET /api/v1/identity-checks lists the organization's checks, newest first. Filter with status, such as status=VERIFIED,FAILED, and with createdAfter, createdBefore, updatedAfter, and updatedBefore. The response has the checks in data, each with audits, data, and verificationUrl set to null. To read audits and data, get the check by ID. While hasMore is true, pass nextCursor as cursor to get the next page. For more information, see Pagination.
Handle errors
400 VALIDATION_FAILED:fullNameorchannelis missing, the channel's address is missing, orexpiresAtisn't in the future.- A check with
statusFAILED: the person canceled, BankID failed, or the name or identity number didn't match. The person can open the link again until it expires. Otherwise, create a new check. - A check with
statusEXPIRED: the person didn't finish beforeexpiresAt. Create a new check.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on