> ## 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. # Usagelimit reached > Fires when the organization reaches its monthly document quota or an eID signature quota, at most once per quota and billing period. Signatures beyond the quota are billed from the balance; documents beyond it are refused until the period ends or the plan changes. `GET /api/v1/limits` returns the current usage. ## OpenAPI ````yaml /api/openapi.json webhook usage.limit_reached 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.