> ## 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. # Get verified signer identities > The identity each eID actually verified, per signature — as opposed to the signer details the sender entered when creating the document. **Why this is a separate endpoint:** `signer.ssn` is what the sender supplied. It is never overwritten with what the eID returned, so the two can differ, and this is where you read the verified one. **One shape for every eID.** Keys are always present and null when a scheme issues nothing, so you never branch on provider to find where the identity lives: - `identity.nationalId` — the national identity number, masked per the workspace's SSN display setting. **Null for schemes that issue none:** MitID without CPR scope, MitID Erhverv, and iDIN, which may never expose a BSN. - `identity.serialNumber` — always present. A stable, non-sensitive reference for this person at your organization. Use it to recognise a returning signer without ever handling a national id. Scoped per organization, so the same person yields a different value for a different customer. - `identity.match` — whether the verified identity matched the intended signer. Computed before masking, so it stays meaningful even when `nationalId` is hidden by policy. `identity` is null for drawn and click-to-sign signatures: nothing verified an identity. **Permissions:** requires the `READ_DOCUMENT` workspace permission and the `signatures:read` scope. `documents:read` alone never returns a national identity number. **Auditing:** every call is recorded on the organization audit log — who read a verified identity and when. The identity values themselves are never logged. You're viewing API version `2026-09`, which is deprecated and stops working on October 1, 2027. To see the current version, select **2026-10** in the menu at the top of the sidebar. To move your integration, see [Upgrading to 2026-10](/upgrading/2026-10). ## OpenAPI ````yaml /api/openapi-2026-09.json get /api/v1/documents/{id}/signatures openapi: 3.0.2 info: title: sajn API version: 1.0.0 description: >- # sajn - API v1 Welcome to the sajn API documentation. This RESTful API allows you to integrate digital document signing capabilities into your applications. ## Overview sajn is a Swedish digital document signing platform that enables you to: - Create and manage digital documents - Add signers and participants to documents - Send documents for signing via email or SMS - Track document status and signatures - Manage contacts and companies - Organize documents with tags and custom fields - Perform identity verification with sajn ID (BankID integration) ## 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 below lists the OAuth scope(s) it requires under 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. ## Pagination List endpoints accept `page` (default 1) and `perPage` (default 10, max 100) and return `totalPages`. The documents, templates and contacts lists also return `total`. The documents list additionally supports cursor pagination: pass the `nextCursor` from a response as `cursor` on the next request. Cursors stay correct while documents are created and updated between requests, which page numbers do not, so use them when mirroring documents into your own system together with 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. 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`; retrying while the first request is still running returns `409`. Responses with a `5xx` status are not stored, so the retry runs again. Keys are scoped to the workspace. ## Webhooks Configure webhooks to receive real-time notifications about document events: - `DOCUMENT_CREATED` - When a document is created - `DOCUMENT_SENT` - When a document is sent for signing - `DOCUMENT_OPENED` - When a signer opens a document - `DOCUMENT_SIGNED` - When a signer signs a document - `DOCUMENT_COMPLETED` - When all signers have signed - `DOCUMENT_REJECTED` - When a signer rejects a document ## Error Handling The API uses standard HTTP status codes and returns error details in JSON format: ```json { "message": "Error description", "code": "NOT_FOUND", "errorId": "..." } ``` `code` is a stable machine-readable identifier; `errorId` identifies the occurrence when you contact support. A `400` for an invalid request lists every problem in `issues` (`[{ "path": "signers.0.email", "message": "..." }]`). A `403` for a missing OAuth scope includes `requiredScopes` and `grantedScopes`. Common status codes: - 200: Success - 400: Bad Request - Invalid parameters - 401: Unauthorized - Invalid or missing API key - 404: Not Found - Resource doesn't exist - 409: Conflict - Resource already exists - 429: Too Many Requests - Rate limit exceeded - 500: Internal Server Error ## 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: hej@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: Signers description: >- [DEPRECATED] Legacy endpoints for document signers. Will stop working in API v2 — use the Parties endpoints instead. - 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. File uploads are handled by a dedicated upload server (upload.sajn.se). - 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 replay 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: /api/v1/documents/{id}/signatures: get: summary: Get verified signer identities description: >- The identity each eID actually verified, per signature — as opposed to the signer details the sender entered when creating the document. **Why this is a separate endpoint:** `signer.ssn` is what the sender supplied. It is never overwritten with what the eID returned, so the two can differ, and this is where you read the verified one. **One shape for every eID.** Keys are always present and null when a scheme issues nothing, so you never branch on provider to find where the identity lives: - `identity.nationalId` — the national identity number, masked per the workspace's SSN display setting. **Null for schemes that issue none:** MitID without CPR scope, MitID Erhverv, and iDIN, which may never expose a BSN. - `identity.serialNumber` — always present. A stable, non-sensitive reference for this person at your organization. Use it to recognise a returning signer without ever handling a national id. Scoped per organization, so the same person yields a different value for a different customer. - `identity.match` — whether the verified identity matched the intended signer. Computed before masking, so it stays meaningful even when `nationalId` is hidden by policy. `identity` is null for drawn and click-to-sign signatures: nothing verified an identity. **Permissions:** requires the `READ_DOCUMENT` workspace permission and the `signatures:read` scope. `documents:read` alone never returns a national identity number. **Auditing:** every call is recorded on the organization audit log — who read a verified identity and when. The identity values themselves are never logged. operationId: getDocumentSignatures parameters: - name: id in: path required: true schema: type: string - name: authorization in: header description: Bearer token for API authentication required: true schema: type: string responses: '200': description: '200' content: application/json: schema: type: object properties: signatures: type: array items: type: object properties: signerId: type: string signerName: type: string description: >- The name on the signer record, as entered by the sender. signedAt: nullable: true identity: description: >- Null when no eID verified this signature — a drawn or click-to-sign signature. type: object properties: provider: type: string description: >- The eID that verified this identity, e.g. SE_BANKID, DK_MITID. Also tells you the format of nationalId. name: description: >- Legal name as reported by the eID — not the name the sender typed. type: string nullable: true nationalId: description: >- National identity number the eID returned, masked per the workspace SSN display setting. Null when the scheme issues none: MitID without CPR scope, and iDIN, which may never expose a BSN. type: string nullable: true nationalIdSuppressed: description: >- Set when a national id exists but the workspace policy hides it. Distinguishes "hidden from you" from "the eID never issued one". type: string enum: - WORKSPACE_POLICY nullable: true serialNumber: description: >- Stable, non-sensitive reference for this person at this organization. Present for every eID. Use it to recognise a returning signer without handling a national id. Scoped per organization, so it cannot be correlated across customers. type: string nullable: true dateOfBirth: description: ISO date, when the scheme reports it. type: string nullable: true company: description: >- Registry-verified organizational identity — MitID Erhverv only. type: object properties: orgNumber: type: string name: type: string nullable: true required: - orgNumber - name additionalProperties: false nullable: true match: type: object properties: status: type: string enum: - MATCH - MISMATCH - NOT_CHECKED method: type: string enum: - SSN - NAME nullable: true required: - status - method additionalProperties: false description: >- Whether the verified identity matched the signer the sender intended. Computed before masking, so it stays meaningful even when nationalId is hidden. required: - provider - name - nationalId - nationalIdSuppressed - serialNumber - dateOfBirth - company - match additionalProperties: false nullable: true required: - signerId - signerName - signedAt - identity additionalProperties: false required: - signatures additionalProperties: false '401': description: Error response content: application/json: schema: type: object properties: message: type: string description: Error message describing what went wrong code: description: Machine-readable error code (e.g. APPROVAL_REQUIRED) type: string errorId: description: >- Identifier for this occurrence — quote it to support when reporting a 500 type: string issues: description: Every validation issue, on a 400 for an invalid request type: array items: type: object properties: path: type: string description: >- Dotted path to the invalid value, e.g. `signers.0.email`; empty for the root message: type: string required: - path - message additionalProperties: false requiredScopes: description: >- OAuth scopes the endpoint requires, on a 403 for a missing scope type: array items: type: string grantedScopes: description: >- OAuth scopes the token was granted, on a 403 for a missing scope type: array items: type: string required: - message additionalProperties: false description: Error response '403': description: Error response content: application/json: schema: type: object properties: message: type: string description: Error message describing what went wrong code: description: Machine-readable error code (e.g. APPROVAL_REQUIRED) type: string errorId: description: >- Identifier for this occurrence — quote it to support when reporting a 500 type: string issues: description: Every validation issue, on a 400 for an invalid request type: array items: type: object properties: path: type: string description: >- Dotted path to the invalid value, e.g. `signers.0.email`; empty for the root message: type: string required: - path - message additionalProperties: false requiredScopes: description: >- OAuth scopes the endpoint requires, on a 403 for a missing scope type: array items: type: string grantedScopes: description: >- OAuth scopes the token was granted, on a 403 for a missing scope type: array items: type: string required: - message additionalProperties: false description: Error response '404': description: Error response content: application/json: schema: type: object properties: message: type: string description: Error message describing what went wrong code: description: Machine-readable error code (e.g. APPROVAL_REQUIRED) type: string errorId: description: >- Identifier for this occurrence — quote it to support when reporting a 500 type: string issues: description: Every validation issue, on a 400 for an invalid request type: array items: type: object properties: path: type: string description: >- Dotted path to the invalid value, e.g. `signers.0.email`; empty for the root message: type: string required: - path - message additionalProperties: false requiredScopes: description: >- OAuth scopes the endpoint requires, on a 403 for a missing scope type: array items: type: string grantedScopes: description: >- OAuth scopes the token was granted, on a 403 for a missing scope type: array items: type: string required: - message additionalProperties: false description: Error response security: - bearerAuth: [] - oauth2: - signatures:read components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Personal API key, e.g. `Authorization: Bearer sajn_sk_...`. Not scope-limited — acts as the issuing user. oauth2: type: oauth2 description: >- OAuth 2.0 access token for a connected application. Limited to the scopes granted at consent. flows: authorizationCode: authorizationUrl: https://app.sajn.se/oauth/authorize tokenUrl: https://app.sajn.se/api/oauth/token refreshUrl: https://app.sajn.se/api/oauth/token scopes: profile:read: >- Läsa din profilinformation, inklusive namn, telefonnummer och e-postadress documents:read: Tillgång till att läsa dina dokument documents:write: >- Tillgång till att skapa nya dokument och redigera dokument som du har skapat documents:delete: >- Tillgång till att ta bort dokument och tillhörande filer, mappar, datafält och kommentarer forms:read: Tillgång till att läsa formulär och inställningar forms:write: Tillgång till att skapa, redigera och publicera formulär forms:delete: Tillgång till att ta bort formulär och svar permanent forms:submissions:read: >- Tillgång till att läsa formulärsvar och respondenternas kontaktuppgifter templates:read: Tillgång till att läsa dina mallar templates:write: Tillgång till att skapa och redigera mallar contacts:read: Tillgång till att läsa dina kontakter contacts:write: Tillgång till att skapa och redigera dina kontakter contacts:delete: Tillgång till att ta bort dina kontakter organization:read: Tillgång till att läsa information om din organisation audit:read: Tillgång till att läsa dokumentaktivitet och händelseloggar signatures:read: >- Tillgång till att läsa vilken identitet e-legitimationen verifierade vid signering, inklusive personnummer sajnid:read: Tillgång till att läsa sajn-id-verifieringar sajnid:write: Tillgång till att skapa sajn-id-verifieringar login:read: Tillgång till att läsa resultatet av inloggningar via sajn Login login:write: Tillgång till att starta inloggningar via sajn Login webhooks:read: Tillgång till att läsa webhooks och deras leveranser webhooks:write: Tillgång till att skapa, redigera och ta bort webhooks actions:read: Tillgång till att läsa föreslagna åtgärder och vad de skulle göra actions:write: >- Tillgång till att godkänna, avfärda och skjuta upp föreslagna åtgärder — ett godkännande kan skicka påminnelser till motparter, säga upp avtal och skapa bevakningar members:read: Tillgång till att läsa arbetsytans medlemmar members:write: Tillgång till att bjuda in och hantera medlemmar roles:read: Tillgång till att läsa arbetsytans roller och behörigheter roles:write: Tillgång till att skapa, redigera och ta bort arbetsytans roller ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.