> ## 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. # Paginated list of employees for this partner ## OpenAPI ````yaml /easyfreelance-partner-api-merged.yaml get /users openapi: 3.0.3 info: title: EasyFreelance Partner API version: 1.0.0 description: > REST API for partners under `/api/v1`. **Authentication:** Every request requires: - `Authorization: Bearer ` — Sanctum personal access token (created in partner **API settings**). - `API-key: ` — Partner API key (same settings). **Idempotency (optional):** Header `Idempotency-key` may be sent on partner requests. - If you omit it, the request behaves normally. - If you send it, the value must be a **valid UUID**; otherwise the API returns **400**. - If the same key has **already been stored** for this partner, the API returns **400** (key already used). That check runs for any route once the key exists in the idempotency store. - **Recommended especially for `POST /payouts`** (create payouts), so safe retries do not create duplicate payout side effects. You typically do not need this header on read-only calls. **Error responses:** Partner endpoints often return JSON with an **`error`** key (string or structured validation payload). Some operations documented here reference Laravel-style responses with a **`message`** field (e.g. unauthenticated). Use HTTP status codes as the primary contract; exact wording of messages may change with locale or small API updates. **Rate limiting:** Authenticated partner traffic shares **one rolling limit per API identity** (Sanctum token / partner user): **500 requests per minute** across all `/api/v1/...` routes. When exceeded, the API returns **429 Too Many Requests**; responses may include a **`Retry-After`** header (seconds). There are no separate per-route partner limits — polling, login links, terms updates, and everything else draw from the same budget. **Entity verification (Veriff / BankID)** — high-level partner flow: 1. Register and get approval for a return URL: `POST /verification-return-urls` (admin approval). The response includes **`requested_url`** (the registered base URL string), **`status`**, and auxiliary fields **`normalized_host`**, **`normalized_scheme`**, and **`normalized_path_prefix`**. Those `normalized_*` values support display, allowlisting, and database uniqueness; **matching** when starting a flow is driven by the stored **`requested_url`** (exactly, or as an approved base plus allowed dynamic path segments per server rules) — not by treating `normalized_path_prefix` as a separate “path template”. 2. Start a session: `POST /users/{id}/verification/flows` with `provider` and `partner_return_url`. The return URL must be **allowed** for your partner against an **approved** `requested_url` as above. 3. Response includes `verification_id` (correlate this ID when **polling** `GET /verification/status/{verificationSession}`) and `verification_url` — open this URL in the end user’s browser. 4. The user completes the flow on EasyFreelance-hosted pages, is redirected to Veriff or BankID, then returns to EasyFreelance; when finished, EasyFreelance redirects the user to `partner_return_url`. 5. The partner backend should poll using `verification_id` until `status` is terminal, and/or consume out-of-band notifications if your deployment offers webhooks (not described in this OpenAPI file). Details and field semantics for verification are documented under the **VerificationFlow** and **VerificationReturnUrlRequest** tags and in the operation descriptions below. servers: - url: https://app.easyfreelance.no/api/v1 description: Production - url: https://test.easyfreelance.no/api/v1 description: Test environment security: - bearer: [] ApiKeyAuth: [] tags: - name: PartnerTerms description: Terms metadata and per-user approval - name: User description: Employees linked to the partner - name: Payout description: Create and list payouts - name: VerificationFlow description: > **Veriff / BankID** verification for employees: register an allowed partner return URL, start a session per user, send the user to `verification_url`, poll with `verification_id`, and finally the user is redirected to your `partner_return_url`. End-to-end: partner return URL approval → `POST …/verification/flows` → browser opens **`verification_url`** (verification bouncer on EasyFreelance) → user is sent to Veriff or BankID → user returns to EasyFreelance → redirect to partner. **`verification_url`** is the same style of bouncer URL for both providers (Veriff then redirects out to the hosted flow; BankID continues in-app). Use `verification_id` as the correlation ID for polling `GET /verification/status/{verificationSession}`. - name: VerificationReturnUrlRequest description: >- Register and track approval of partner return URLs used after verification. paths: /users: get: tags: - User summary: Paginated list of employees for this partner operationId: user.fetchUsers parameters: - name: page in: query schema: type: string default: 1 - name: page_size in: query schema: type: string default: 25 responses: '200': description: Paginated users content: application/json: schema: type: object properties: total: type: integer next: type: string nullable: true previous: type: string nullable: true count: type: integer results: 51bc5454-013d-443c-a79b-3df2de8e5e2a required: - total - next - previous - count - results '401': $ref: '#/components/responses/AuthenticationException' components: responses: AuthenticationException: description: Unauthenticated content: application/json: schema: type: object properties: message: type: string description: Error overview. required: - message securitySchemes: bearer: type: http scheme: bearer description: Sanctum personal access token (`access_tokens` / partner API settings). ApiKeyAuth: type: apiKey in: header name: API-key description: UUID API key stored for the partner user. ````