> ## Documentation Index > Fetch the complete documentation index at: https://docs.sajn.se/llms.txt > Use this file to discover all available pages before exploring further. # Webhooktest > Sent to one webhook when you call `POST /api/v1/webhooks/{id}/test`, to check that your endpoint receives and verifies deliveries. No other webhook receives it, and `GET /api/v1/events` doesn't list it. ## OpenAPI ````yaml /api/openapi.json webhook webhook.test openapi: 3.1.0 info: title: sajn API version: 2026-10 description: >- # sajn - API v1 With the sajn REST API, you can add digital document signing to your own applications. ## Overview sajn is a Swedish digital document signing platform. With the API, you can: - Create and manage documents and templates - Add the parties who sign, review, or organize a document - Send documents for signing by email or SMS - Track document status and signatures - Manage contacts and companies - Organize documents with tags and custom fields - Verify identities with sajn ID, through BankID and other eIDs ## Authentication Every endpoint (except the health check) requires a bearer token in the Authorization header: ``` Authorization: Bearer YOUR_TOKEN ``` Two kinds of token are accepted: - **Personal API key** (`sajn_sk_...`) — generated from your workspace developer settings. Acts as the issuing user; can reach any endpoint the user's workspace role permits. - **OAuth 2.0 access token** — issued via the authorization-code flow (PKCE for public clients) to a connected application. Bound to one workspace and limited to the **scopes** the user granted at consent — effective access is *workspace role ∩ granted scopes*. Each operation lists the OAuth scopes it requires in its security section. The scopes are coarse and resource-oriented (e.g. `documents:read`, `documents:write`, `documents:delete`, `contacts:read`). Personal API keys are not scope-limited; OAuth tokens are. ## Rate Limiting Limits apply per organization and scale with the plan: | Plan | Per minute | Per day | |---|---|---| | Basic | 60 | 2 000 | | Solo | 120 | 10 000 | | Team | 600 | 100 000 | | Enterprise | 2 000 | 2 000 000 | | Sandbox | 60 | 2 000 | Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` for the minute window, and `X-RateLimit-Daily-Limit`, `X-RateLimit-Daily-Remaining` and `X-RateLimit-Daily-Reset` for the daily quota. A `429` response includes `Retry-After` in seconds. ## Query parameters Query parameters are plain strings, such as `?externalId=12345&archived=false`: - Booleans are `true` or `false`. - Dates are ISO 8601 dates (`2026-10-01`) or date-times (`2026-10-01T08:00:00Z`). A date-time without an offset is UTC. - Filters that take several values accept a comma-separated list (`status=PENDING,COMPLETED`) or a repeated parameter (`status=PENDING&status=COMPLETED`). An unknown query parameter returns `400`, so a misspelled filter never silently returns everything. ## Pagination Every list returns `{ data, hasMore, nextCursor }`. To walk a list, pass `nextCursor` as `cursor` on the next request, keep the other parameters unchanged, and stop when `hasMore` is `false`. `limit` sets the page size, from 1 to 100, with a default of 25. To get the number of items that match the filters, pass `include=total`, and the response adds `total`. Lists sort newest first. To sort another way, pass `orderBy` and `orderDirection` where the list takes them. A list bounded by its parent, such as a document's parties, returns every item in one response, with `hasMore` set to `false` and `nextCursor` set to `null`. On the documents list, the cursor is keyset-based: it stays correct while documents are created and updated between requests. To mirror documents into your own system, sort by `updatedAt` and use the `updatedAfter` filter. ## Idempotent requests Send an `Idempotency-Key` header (any unique string up to 255 characters, for example a UUID) on `POST`, `PATCH` or `DELETE` requests to make retries safe. The first request runs normally and its response is stored for 24 hours, errors included. A retry with the same key and the same method, path and body returns the stored response with the header `Idempotent-Replayed: true`. Reusing a key with a different request returns `400 IDEMPOTENCY_KEY_REUSED`; retrying while the first request is still running returns `409 IDEMPOTENCY_KEY_IN_USE` with `Retry-After`. Responses with a `429` or `5xx` status aren't stored, so the retry runs again. Keys are scoped to the workspace. ## Versioning The API is versioned by date (`YYYY-MM`), and this reference documents version `2026-10`. To choose the version for a request, send the `Sajn-Version` header: ``` Sajn-Version: 2026-10 ``` Without the header, a request uses your organization's default version. An organization without a default is pinned to the latest version by its first request. Every response returns the version that served it in `Sajn-Version`. On a deprecated version, responses also carry `Deprecation` and `Sunset` headers, and from the sunset date its requests return `400`. For details, see https://docs.sajn.se/api-reference/versioning. ## Webhooks Each webhook endpoint has its own API version, set when you create it, that decides the payload shape. Deliveries carry it in the `Sajn-Version` header. The delivery body is the event, `{ id, type, createdAt, apiVersion, workspaceId, environment, actor, data }`, signed according to [Standard Webhooks](https://www.standardwebhooks.com) in the `webhook-id`, `webhook-timestamp` and `webhook-signature` headers. Common document events: - `document.created` - A document is created. - `document.sent` - A document is sent for signing. - `document.party.opened` - A party opens the document. - `document.party.signed` - A party signs the document. - `document.fully_signed` - Every signer has signed, before the document is sealed. - `document.completed` - The document is sealed and complete. - `document.rejected` - A party rejects the document. For every event type, see `POST /api/v1/webhooks`. ## Error Handling Every error response has the same JSON shape: ```json { "code": "NOT_FOUND", "message": "Document not found", "userMessage": "Dokumentet hittades inte.", "requestId": "req_V1StGXR8Z5jdHi6BmyT2", "resource": "document" } ``` - `code` is always present and comes from the closed list in the following table. Branch on it, not on the status or the message. - `message` is English text for developers. When the operation has no more specific text, it's the meaning of `code` from the following table. Its wording can change, so don't parse it. - `userMessage` is always present. It's text that is safe to show your users, usually in Swedish. - `requestId` identifies the request and matches the `Sajn-Request-Id` header, which every response carries. Quote it when you contact support. On a replayed idempotent response, it identifies the original request. A `400 VALIDATION_FAILED` lists every problem in `issues`: `[{ "path": "parties.0.email", "code": "INVALID_FORMAT", "message": "Invalid email address" }]`. An issue `code` is one of `INVALID_TYPE`, `INVALID_FORMAT`, `INVALID_VALUE`, `TOO_SMALL`, `TOO_BIG` or `UNRECOGNIZED_KEY`, and an issue that no single input caused has an empty `path`. A `404 NOT_FOUND` names the type of the missing resource in `resource`, such as `document` or `party`, or `null` when the API can't tell. A `403 INSUFFICIENT_SCOPE` includes `requiredScopes` and `grantedScopes`. A `401 UNAUTHORIZED` always means the credential itself is missing, invalid, expired or revoked. A valid token that isn't allowed to do something gets a `403`. A `409 INVALID_STATE` means the resource's state doesn't allow the operation; change the state first, then retry. A `503 UPSTREAM_UNAVAILABLE` is safe to retry with exponential backoff, and so is a `429` after `Retry-After` seconds. The API returns the following codes: | Code | Status | Meaning | |---|---|---| | `VALIDATION_FAILED` | 400 | The request failed validation. `issues` lists every problem. | | `INVALID_JSON` | 400 | The request body isn't valid JSON. | | `EXPIRED` | 400 | The link, code or resource has expired. | | `IDEMPOTENCY_KEY_REUSED` | 400 | The `Idempotency-Key` was already used with a different request. | | `INVALID_API_VERSION` | 400 | The `Sajn-Version` header names a version that doesn't exist. | | `API_VERSION_SUNSET` | 400 | The requested version, or your organization's default, is past its sunset date. | | `UNAUTHORIZED` | 401 | The API token is missing, invalid, expired or revoked. | | `PERMISSION_DENIED` | 403 | The token's user isn't allowed to perform the operation, for example because their workspace role lacks a permission. | | `INSUFFICIENT_SCOPE` | 403 | The OAuth token wasn't granted a scope the operation requires. See `requiredScopes` and `grantedScopes`. | | `PLAN_REQUIRED` | 403 | The organization's plan doesn't include API access or the feature. | | `ACCOUNT_INACTIVE` | 403 | The organization, user or membership behind the token is deactivated or suspended. | | `ACCOUNT_SETUP_REQUIRED` | 403 | The organization must finish its setup, such as verifying an accountable person, first. | | `LIMIT_EXCEEDED` | 403 | A plan limit was reached, such as the monthly number of sent documents. | | `APPROVAL_REQUIRED` | 409 | The operation needs an approval first, such as sending a document that the workspace requires an approval for. Request one with `POST /api/v1/approval-requests`. | | `NOT_FOUND` | 404 | The resource doesn't exist, or the token can't access it. `resource` names its type, such as `document`, or is `null` when the API can't tell. | | `ROUTE_NOT_FOUND` | 404 | No endpoint matches the method and path in the requested API version. | | `INVALID_STATE` | 409 | The resource's current state doesn't allow the operation, such as editing a document that was already sent or downloading a file that isn't produced yet. | | `ALREADY_EXISTS` | 409 | A resource with the same unique value, such as `externalId`, already exists. | | `IDEMPOTENCY_KEY_IN_USE` | 409 | A request with the same `Idempotency-Key` is still running. Retry after `Retry-After` seconds. | | `RATE_LIMITED` | 429 | The per-minute rate limit was reached. Retry after `Retry-After` seconds. | | `DAILY_QUOTA_EXCEEDED` | 429 | The daily request quota was reached. Retry after `Retry-After` seconds. | | `INTERNAL_ERROR` | 500 | Something went wrong on sajn's side. Quote `requestId` when you contact support. | | `UPSTREAM_UNAVAILABLE` | 503 | A service the operation depends on, such as an eID provider or a connected integration, failed or is unavailable. Retry with exponential backoff. | ## Support For API support, documentation, or questions: - Email: dev@sajn.se - Documentation: https://docs.sajn.se - Status: https://status.sajn.se contact: name: sajn Support email: dev@sajn.se url: https://www.sajn.se/support license: name: Policy url: https://www.sajn.se/allmanna-villkor servers: - url: https://app.sajn.se description: Production server security: [] tags: - name: Health description: API health and version information - name: Documents description: Create, manage, and send documents for signing - name: Templates description: Create and manage templates that can be used to spin up new documents - name: Parties description: Manage document parties (signers and other participants) - name: Contacts description: Manage contacts and contact information - name: Companies description: Manage companies and organizations - name: Fields description: Manage document fields and sections - name: Tags description: Organize documents with tags - name: Custom Fields description: Define and manage custom fields for documents - name: sajn ID description: Identity verification with Swedish BankID - name: Files description: >- Upload and manage files. `POST /api/v1/files` returns a presigned URL that you upload the bytes to. - name: Folders description: Organize documents and templates into hierarchical folders - name: Comments description: Thread-based discussion on documents - name: Reminders description: Send and inspect signing reminders on a document - name: Helpers description: 'Reference data: languages, countries, currencies, timezones' - name: Organization description: Authenticated organization metadata and branding - name: Webhook Deliveries description: Inspect and retry past webhook deliveries - name: Delegations description: Read-only access to signer delegation events on a document - name: Blocks description: Reusable library blocks for templates paths: {} ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.