Skip to main content
In this recipe, you check a new customer’s identity with sajn ID before you send them a contract. The customer identifies with BankID first. When the check succeeds, your service sends the contract, set up so the customer signs with BankID and their identity number is matched again at signing. Use this flow when you must know who the customer is before they see the contract, such as for a credit agreement. If verifying at signing is enough, set the party’s signing method to an eID instead; see Set the signing method for a party.

Before you begin

  • Node.js 18 or later, and Express: npm install express.
  • An API key in the SAJN_API_KEY environment variable. To create one, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys).
  • A webhook endpoint subscribed to identity_check.verified, identity_check.failed, and identity_check.cancelled, with its secret in SAJN_WEBHOOK_SECRET. For more information, see Webhooks.
  • A contract template. Store its ID in SAJN_TEMPLATE_ID.

Build the flow

1

Start the identity check

When the customer applies, create an identity check. Put your application’s ID in reference, so the webhook can find it:
sajn emails the customer a link right away. With nationalId, BankID checks that the person has that identity number; without it, BankID checks the name.
2

Send the contract when the check succeeds

In your webhook handler, act on the three outcomes. On identity_check.verified, create the contract with the customer as a party that signs with BankID, and send it:
The handler uses the following:
  • data.object is the identity check, and its reference is the value you sent, so findApplication can look up the application. For the signature headers, see Verify webhook signatures.
  • The nationalId on the party makes BankID match the same identity number again at signing. A party in POST /api/v1/documents doesn’t take nationalId, so the handler sets it with a party update. The create request returns the whole document, so the party’s id is in parties.
  • The idempotency keys make a repeated delivery of the same event replay the first responses instead of sending a second contract.
3

Check the party's identity afterward

After the contract is signed, each party has identityVerified and identityMismatch. identityMismatch is true when the BankID identity didn’t match the intended party and the signature was still recorded. For the verified identities, call GET /api/v1/documents/DOCUMENT_ID/signatures.

Handle errors

  • identity_check.failed or identity_check.cancelled: the customer didn’t pass the check. Ask them to try again, and start a new check if the link expired.
  • 403 PERMISSION_DENIED on send: BankID signing isn’t included in your plan. For the plan rules, see Set the signing method for a party.
  • The identity number is personal data. Store it only as long as you need it, and keep it out of your logs.
For the error shape and every code, see Errors.