Tunnista.fi-rajapinta

Näin se toimii

1. Luo tunnistus valitulle lomakkeelle. Saat vastauksena asiakkaan henkilökohtaisen linkin.
2. Ohjaa asiakas linkkiin omassa palvelussasi tai viestissäsi. Asiakas tunnistautuu ja täyttää lomakkeen.
3. Saat tuloksen webhookilla heti, kun asiakas on valmis, tai kysymällä tilaa.

Avain ja pyyntöraja

Lähetä avain jokaisessa pyynnössä otsakkeessa Authorization: Bearer tf_live_…. Avain näytetään vain luonnin yhteydessä, joten tallenna se heti turvaan.

Pyyntöraja: Pro 60 / min, Plus 300 / min avainta kohden.

Luo tunnistus

POST /api/public/v1/verifications · oikeus verifications:write · lomakkeen pitää olla julkaistu.

curl -X POST https://tunnista.fi/api/public/v1/verifications \
  -H "Authorization: Bearer $TUNNISTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-asiakas-1234" \
  -d '{
    "form_id": "LOMAKKEEN_ID",
    "recipient": { "email": "asiakas@example.com", "name": "Matti Meikäläinen" },
    "external_ref": "crm-asiakas-1234",
    "expires_in_days": 30
  }'

Vastaus 201

{
  "id": "6f1c…",
  "object": "verification",
  "status": "pending",
  "form_id": "LOMAKKEEN_ID",
  "external_ref": "crm-asiakas-1234",
  "recipient": { "email": "asiakas@example.com", "name": "Matti Meikäläinen" },
  "created_at": "2026-10-22T10:00:00Z",
  "expires_at": "2026-11-21T10:00:00Z",
  "completed_at": null,
  "response": null,
  "url": "https://tunnista.fi/f/lomake?invite=…"
}

Tallenna id ja ohjaa asiakas osoitteeseen url. Linkki näytetään vain tässä vastauksessa.

Tuplien esto

Lähetä otsake Idempotency-Key. Kun sama avain tulee uudelleen, saat saman vastauksen eikä uutta tunnistusta luoda. Näin uudelleenyritys verkkovirheen jälkeen on turvallinen.

Tarkista tila

GET /api/public/v1/verifications/:id · oikeus verifications:read

Vastauksen kentät

Lisää ?include=answers, niin saat lomakkeen vastaukset mukaan (oikeus responses:read). Arkaluonteisia kenttiä, kuten henkilötunnusta, ei palauteta.

Listaa tunnistukset

GET /api/public/v1/verifications?external_ref=…&limit=25 palauttaa rajapinnalla luodut tunnistukset uusimmasta alkaen. limit on 1–100, oletus 25.

Webhookit

Lisää osoite kohdassa Asetukset → Rajapinta ja webhookit. Saat ilmoituksen näistä tapahtumista:

• verification.completed – tunnistus valmistui
• response.submitted – lomake lähetettiin
• signature.completed – allekirjoitus valmistui
• risk_flag.created – vastauksesta löytyi tarkistettavaa

Vastaa 2xx-koodilla 10 sekunnin kuluessa. Muuten toimitusta yritetään uudelleen porrastetusti.

Tarkista jokaisen kutsun aitous otsakkeesta X-Tunnista-Signature: t=AIKALEIMA,v1=ALLEKIRJOITUS. Allekirjoitus on HMAC-SHA256 merkkijonosta AIKALEIMA.body.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Virheet

Virheet palautetaan muodossa { "error": { "code", "message" } }.