Verifiering (KYC / ID)

Flödet från början till slut

Registrera en return-URL

POST /verification-return-urls med den URL användaren ska skickas tillbaka till. Svaret innehåller requested_url och status. Godkännandet görs manuellt av EasyFreelance och kan ta tid – 201 betyder registrerad, inte godkänd. Använd GET /verification-return-urls för att se status.
Starta en session

POST /users/{id}/verification/flows med provider och partner_return_url. URL:en måste vara tillåten för er partner, mätt mot en godkänd requested_url. Är den inte det får ni 422.
Skicka användaren till verification_url

Svaret innehåller verification_id och verification_url. Öppna URL:en i slutanvändarens webbläsare. Den pekar alltid på EasyFreelance verifieringssida, som sedan skickar användaren vidare till Veriff eller BankID.
Användaren slutför och kommer tillbaka

Efter Veriff eller BankID skickas användaren tillbaka till EasyFreelance, och därifrån vidare till partner_return_url.
Polla tills status är terminal

GET /verification/status/{verificationSession} med verification_id som ID. Polla var 2:e–5:e sekund. Alternativt, eller som komplement, kan ni lyssna på employee.verified-webhooken och hämta GET /users/{id} för slutgiltigt resultat.

Leverantörer

provider	id_type	Använd
`veriff`	`local`	Veriff-integrationen för norska ID-handlingar.
`veriff`	`international`	Veriff-integrationen som endast tar emot utländska dokument.
`bankid`	—	BankID. `id_type` kan utelämnas och returneras som `null`.

Obs

id_type är obligatorisk när provider är veriff. De två Veriff-integrationerna är ömsesidigt uteslutande: local godtar inte utländska dokument, och international godtar inte norska. Välj rätt variant innan ni skickar iväg användaren.

Return-URL:en

När en session är terminal skickar EasyFreelance användaren till partner_return_url med dessa frågeparametrar tillagda. Er sida måste klara av – och helst läsa – dem.

Parameter	Exempel
`verification_id`	`550e8400-e29b-41d4-a716-446655440000`
`provider`	`bankid` eller `veriff`
`status`	`approved`, `incomplete`, `error` …

Blanda inte dessa

Fälten normalized_host, normalized_scheme och normalized_path_prefix i return-URL-svaret är till för visning, allowlisting och unikhet i databasen. Själva matchningen när ett flöde startas görs mot lagrad requested_url – normalized_path_prefix är inte en egen ”path-mall”.

Statusvärden

status	Terminal	Betydelse
`pending`	Nej	Sessionen är skapad, användaren är inte klar.
`approved`	Ja	Leverantören är OK och identiteten är komplett.
`incomplete`	Ja	Leverantören är OK, men identitetsfält saknas.
`declined`	Ja	Verifieringen avvisades.
`error`	Ja	Fel under genomförandet – till exempel duplicerat personnummer.
`expired`	Ja	Sessionen gick ut innan användaren blev klar.
`cancelled`	Ja	Användaren avbröt.

next_action

next_action är alltid satt i pollningssvaret och talar om vad er klient bör göra härnäst.

next_action	När	Gör så här
`continue_verification`	`pending`	Fortsätt polla.
`redirect_to_partner`	`approved`	Skicka användaren vidare i ert eget flöde.
`retry_verification`	`incomplete`	Be användaren starta om verifieringen.
`contact_support`	`error` med dubblerat personnummer	Kräver manuell uppföljning – kontakta EasyFreelance.
`retry`	`declined` och andra fel	Låt användaren försöka igen.
`show_error`	`expired`, `cancelled`	Visa ett felmeddelande och erbjud en ny start.

id_verification_detail

Samma struktur returneras på GET /users/{id}, i användarlistan, vid uppslag, vid pollning och i webhooken. Använd reason_codes till automatik och partner_instructions till text som ni kan visa vidare.

reason_code	Betydelse
`ssn_not_provided`	Leverantören returnerade inget personnummer.
`ssn_duplicate`	Personnumret finns redan i systemet. Kräver manuell uppföljning – kontakta support.
`birthday_not_provided`	Födelsedatum saknas.
`provider_data_incomplete`	Entiteten är godkänd, men identitetsdata är ofullständiga.
`veriff_missing_id_number`	Veriff returnerade inget ID-nummer.
`veriff_missing_date_of_birth`	Veriff returnerade inget födelsedatum.
`veriff_missing_document_country`	Veriff returnerade inget dokumentland.

Pollningssvar med incomplete

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": 123,
  "provider": "bankid",
  "id_type": null,
  "status": "incomplete",
  "verified_at": "2026-07-08T12:00:00+00:00",
  "expires_at": "2026-07-08T12:30:00+00:00",
  "next_action": "retry_verification",
  "last_polled_at": "2026-07-08T12:00:05+00:00",
  "id_verification_detail": {
    "complete": false,
    "entity_status": "approved",
    "provider": "BankID",
    "missing_fields": [
      "identification"
    ],
    "reason_codes": [
      "ssn_not_provided"
    ],
    "partner_instructions": [
      {
        "code": "retry_verification",
        "message": "Identity verification partially completed. Missing national ID number."
      }
    ]
  }
}

Duplicerat personnummer

Får ni status: error med ssn_duplicate, är numret redan registrerat i systemet. Detta kan inte lösas via API:et – kontakta [email protected] och ange användar-ID.

På GET /users/{id} hämtar servern automatiskt den senaste terminala ssn_duplicate-sessionen för er partner, så att detta resultat dyker upp utan att ni behöver skicka med verification_id.

Webhook

Slår ni på employee.verified i API-inställningarna skickar vi ett POST-anrop till er callback-URL när verifieringen är klar. Det är ett bra alternativ till frekvent pollning. Se Webhooks på engelska.

Kom i gång

Flöden

Referens

Flödet från början till slut

Registrera en return-URL

Starta en session

Skicka användaren till verification_url

Användaren slutför och kommer tillbaka

Polla tills status är terminal