> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.easyfreelance.no/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 `status`201 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