Verifisering (KYC / ID)

Flyten fra ende til ende

Registrer en return-URL

POST /verification-return-urls med URLen brukeren skal sendes tilbake til. Svaret inneholder requested_url og status. Godkjenningen gjøres manuelt av EasyFreelance og kan ta tid – 201 betyr registrert, ikke godkjent. Bruk GET /verification-return-urls for å se status.
Start en sesjon

POST /users/{id}/verification/flows med provider og partner_return_url. URLen må være tillatt for partneren deres, målt mot en godkjent requested_url. Er den ikke det, får dere 422.
Send brukeren til verification_url

Svaret inneholder verification_id og verification_url. Åpne URLen i nettleseren til sluttbrukeren. Den peker alltid til EasyFreelance sin verifiseringsside, som deretter sender brukeren videre til Veriff eller BankID.
Brukeren fullfører og kommer tilbake

Etter Veriff eller BankID sendes brukeren tilbake til EasyFreelance, og derfra videre til partner_return_url.
Poll til status er terminal

GET /verification/status/{verificationSession} med verification_id som ID. Poll hvert 2.–5. sekund. Alternativt, eller i tillegg, kan dere lytte på employee.verified-webhooken og hente GET /users/{id} for endelig resultat.

Leverandører

provider	id_type	Bruk
`veriff`	`local`	Veriff-integrasjonen for norske ID-dokumenter.
`veriff`	`international`	Veriff-integrasjonen som kun tar imot utenlandske dokumenter.
`bankid`	—	BankID. `id_type` kan utelates, og returneres som `null`.

Merk

id_type er påkrevd når provider er veriff. De to Veriff-integrasjonene er gjensidig utelukkende: local godtar ikke utenlandske dokumenter, og international godtar ikke norske. Velg riktig variant før dere sender brukeren av gårde.

Return-URLen

Når en sesjon er terminal, sender EasyFreelance brukeren til partner_return_url med disse spørringsparametrene påhengt. Siden deres må tåle – og helst lese – dem.

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

Ikke bland disse

Feltene normalized_host, normalized_scheme og normalized_path_prefix i return-URL-svaret er til visning, allowlisting og unikhet i databasen. Selve matchingen når en flyt startes, gjøres mot lagret requested_url – normalized_path_prefix er ikke en egen «path-mal».

Statusverdier

status	Terminal	Betydning
`pending`	Nei	Sesjonen er opprettet, brukeren er ikke ferdig.
`approved`	Ja	Leverandøren er OK og identiteten er komplett.
`incomplete`	Ja	Leverandøren er OK, men identitetsfelter mangler.
`declined`	Ja	Verifiseringen ble avvist.
`error`	Ja	Feil under gjennomføring – for eksempel duplisert fødselsnummer.
`expired`	Ja	Sesjonen gikk ut før brukeren ble ferdig.
`cancelled`	Ja	Brukeren avbrøt.

next_action

next_action er alltid satt på pollesvaret, og forteller hva klienten deres bør gjøre videre.

next_action	Når	Gjør dette
`continue_verification`	`pending`	Fortsett å polle.
`redirect_to_partner`	`approved`	Send brukeren videre i deres egen flyt.
`retry_verification`	`incomplete`	Be brukeren starte verifiseringen på nytt.
`contact_support`	`error` med duplisert fødselsnummer	Krever manuell oppfølging – kontakt EasyFreelance.
`retry`	`declined` og andre feil	La brukeren prøve igjen.
`show_error`	`expired`, `cancelled`	Vis en feilmelding og tilby ny start.

id_verification_detail

Samme struktur returneres på GET /users/{id}, i brukerlisten, på oppslag, på polling og i webhooken. Bruk reason_codes til automatikk og partner_instructions til tekst dere kan vise videre.

reason_code	Betydning
`ssn_not_provided`	Leverandøren returnerte ikke fødselsnummer.
`ssn_duplicate`	Fødselsnummeret finnes allerede i systemet. Krever manuell oppfølging – kontakt support.
`birthday_not_provided`	Fødselsdato mangler.
`provider_data_incomplete`	Entiteten er godkjent, men identitetsdata er ufullstendig.
`veriff_missing_id_number`	Veriff returnerte ikke ID-nummer.
`veriff_missing_date_of_birth`	Veriff returnerte ikke fødselsdato.
`veriff_missing_document_country`	Veriff returnerte ikke dokumentland.

Pollesvar 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."
      }
    ]
  }
}

Duplisert fødselsnummer

Får dere status: error med ssn_duplicate, er nummeret allerede registrert i systemet. Dette kan ikke løses via API-et – ta kontakt med [email protected] og oppgi bruker-ID.

På GET /users/{id} henter serveren automatisk den siste terminale ssn_duplicate-sesjonen for partneren deres, slik at dette resultatet dukker opp uten at dere trenger å sende med verification_id.

Webhook

Slår dere på employee.verified i API-innstillingene, sender vi et POST-kall til callback-URLen deres når verifiseringen er ferdig. Det er et godt alternativ til hyppig polling. Se Webhooks på engelsk.

Kom i gang

Flyter

Referanse

Flyten fra ende til ende

Registrer en return-URL

Start en sesjon

Send brukeren til verification_url

Brukeren fullfører og kommer tilbake

Poll til status er terminal