Onboarding

Denne guiden beskriver den anbefalte rekkefølgen for å opprette eller koble en ansatt og fullføre alle onboarding-steg via Partner API /api/v1). Full referanse finnes i OpenAPI/Mintlify-dokumentasjonen.

​

Forutsetninger

• Autentisering på alle kall: Authorization: Bearer <Sanctum token> og API-key: <partner-API-nøkkel>.
• Base-URL: https://<miljø>/api/v1 (f.eks. app.easyfreelance.no eller testmiljø).

​

Onboarding (v2) - Status

GET /users/{id} (og status-polling for verifisering) returnerer onboarding med status_version: "v2". Stegene er: Steg onboarding.steps) Betydning

• email_verified | E-post er bekreftet |
• terms_approved | Vilkår godkjent for brukeren |
• profile | Full profil er registrert UserProfile) |
• id_verification | Enhetsverifisering er godkjent og identitet (Veriff/BankID) er fullført |
• bank_account | Bankkonto er registrert |

Når onboarding.is_onboarded er true, er missing_steps tom. Ansatte opprettet med POST /users får vanligvis e-post verifisert med én gang; resten må dere sette via API som beskrevet under.

​

Onboarding (v2) - Flyt

1. Forbered: godkjent retur-URL for verifisering] —>
2. POST /users – opprett eller koble ansatt
3. GET /users/id – sjekk onboarding]
4. POST /users/id/terms – godkjenn vilkår
5. PUT /users/id/profile – full profil
6. Bank allerede satt?
   1. Nei? → PATCH/PUT /users/id – bank
   2. Ja? → POST /users/id/verification/flows
7. Åpne verification_url i nettleser
8. Poll GET /verification/status/sessionId
9. Terminal status?
   1. Nei? → Hopp til Steg 9
   2. Ja? → GET /users/id – is_onboarded true

Engangs-setup før verifisering: partner_return_url Som brukes i verifiseringsflyten må være registrert og godkjent av EasyFreelance (se steg 1). Uten dette får dere avslag når dere starter en verifiseringsøkt.

​

Steg for steg guide

Følg denne guiden for å fullføre onboarding per bruker.

​

Registrere URL

Registrer og få godkjent partner_return_url

1. POST /verification-return-urls med partner_return_url (den URL-en dere vil sende brukeren tilbake til etter ID-verifisering).
2. Vent til status er godkjent i deres interne flyt / hos EasyFreelance-admin (API-et returnerer status201 betyr ikke nødvendigvis godkjent ennå.
3. Bruk nøyaktig samme (eller tillatt utvidelse av) URL som partner_return_url når dere kaller POST /users/{id}/verification/flows senere.
4. Dynamisk path-del: Dere kan registrere en base-URL og bruke lengre stier som bygger på den (i tråd med serverens regler for godkjent base pluss valgfrie suffiks-segmenter). I den dynamiske delen — hvert ekstra path-segment etter den godkjente base-stien — tillater vi kun bokstaver (A–Z, a–z) og tall (0–9) per segment. Ingen bindestreker, understreker eller andre tegn i disse segmentene (f.eks. .../callback/abc123 er ok; .../callback/user-42 Er ikke ok).

​

1. Opprett eller koble ansatt

• POST /users med bl.a. email og valgfritt internal_id, profil-/bankfelter.
• Hvis e-posten allerede finnes, kobles brukeren til partneren; responsen er som GET /users/{id}.
• Les id fra responsen – det er deres user_id for videre kall.

Valgfritt: POST /users/lookup med nøyaktig én av user_id, phone eller ssn for å finne en ansatt dere allerede har koblet.

​

2. Godkjenn vilkår

• Hent metadata: GET /terms (eller GET /users/{id}/terms for status per bruker).
• Registrer godkjenning: POST /users/{id}/terms med { "approved": true }.

​

3. Fullfør profil

• PUT /users/{id}/profile (eller PATCH) med alle påkrevde felter: navn, adresse, postnummer, sted, retningsnummer, telefon, main_work "true" / "false").

Dette er den anbefalte måten å fullføre profile-steget på i partner-API-et.

​

4. Bankkonto

• Hvis ikke satt ved opprettelse: PATCH /users/{id} (eller PUT) med enten norsk kontonummer eller IBAN + BIC (ikke bland stiler – se API-beskrivelsen).
• Når konto finnes, er bank_account-steget oppfylt.

Rekkefølge mellom profil og bank kan i praksis tilpasses deres UX, men begge må være på plass før is_onboarded kan bli sann (sammen med øvrige steg).

​

5. ID-verifisering (Veriff eller BankID)

1. POST /users/{id}/verification/flows med:
   • partner_return_url (må matche godkjent URL fra steg 0),
   • provider: veriff eller bankid,
   • for Veriff: id_type: local eller international.
2. Fra 201-responsen: åpne verification_url i brukerens nettleser (verifiserings-bouncer på EasyFreelance; samme type URL for både Veriff og BankID — deretter Veriff eller BankID-flyt).
3. Poll GET /verification/status/{verificationSession} med verification_id fra responsen til status er terminal approved, declined, cancelled, expired, error).
4. onboarding i status-responsen speiler samme v2-struktur som GET /users/{id} – når id_verification er fullført og øvrige steg er grønne, er brukeren ferdig onboardet.

Ved feil eller utløpt økt kan brukeren starte en ny verifiseringsflyt (ny POST …/verification/flows).

​

6. Verifiser ferdig onboarding

• GET /users/{id} til onboarding.is_onboarded er true.

​

Pollingsråd

• Bruk verification_id som {verificationSession} i status-endepunktet.
• Intervall: anbefal å polle GET /verification/status/{verificationSession} med ca. 2–5 sekunders mellomrom mellom hvert kall mens status er pending.
• Stol på expires_at på verifiseringsøkta; start flyten snart etter opprettelse.

​

Vanlige årsaker til at is_onboarded forblir false

• missing_steps inneholder | Typisk tiltak |
• terms_approved | POST /users/{id}/terms med approved: true |
• profile | PUT /users/{id}/profile med komplett kropp |
• bank_account | PATCH /users/{id} med gyldig bankfelter |
• id_verification | Fullfør Veriff/BankID-flyt; sjekk at retur-URL var godkjent og at identitet er ferdig i systemet |

​

Relaterte endepunkter (ikke alltid nødvendig for onboarding)

• POST /users/{id}/login-link – magisk innloggingslenke til ansatt (f.eks. support).
• GET/POST /payouts – Utbetalinger krever at ansatt er knyttet til partner og at utbetalingslogikk er klar; dette er etter onboarding om dere utbetaler via plattformen