> ## 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. # Create a new document > Create a new document in DRAFT status. You can optionally include parties, metadata, and responsible user during creation. **Document Types:** - `SIGNABLE` (default) - Standard signing document - `ACCEPTABLE` - Document that requires acceptance rather than signature - `ARCHIVE_IMPORTED` - Imported from external archive **Template Support:** Use `templateId` to create a document from a template. Template fields and template parties are automatically copied unless `parties` are explicitly provided in the request. **CRM Link:** Use `integrationLink` to link the document to a CRM record (currently HubSpot deals). When the workspace has a field mapping configured for the integration, mapped custom fields and product-table rows are prefilled from the record, and signing status is written back to it. Explicit `customFields` in the request take precedence over prefilled values. **Responsible User:** Use `responsibleUserId` to assign a specific team member as responsible for the document. Defaults to the creating user if not specified. **Adding Parties:** Two approaches are supported: 1. **Contact-based** (recommended): Provide `contactId` to reference existing contacts - automatically inherits all contact details 2. **Manual**: Provide `name` and `email` to manually specify party details > **Note:** The legacy `signers` field is also accepted as input for backwards compatibility, but is deprecated and will stop working in API v2. Use `parties` going forward. If both are provided, `parties` takes precedence. **Party Examples:** ```json { "parties": [ { "contactId": "contact-123", "role": "SIGNER", "signingOrder": 1, "deliveryMethod": "EMAIL", "requiredSignature": "BANKID" }, { "name": "John Doe", "email": "john@example.com", "role": "SIGNER", "signingOrder": 2, "deliveryMethod": "SMS", "requiredSignature": "DRAWING" } ] } ``` **Per-Party Settings:** - `deliveryMethod` - How to notify: `EMAIL` (default), `SMS`, or `NONE` - `requiredSignature` - Signature type: `DRAWING`, `BANKID` (Swedish BankID), `CLICK_TO_SIGN`, `MANUAL`, or a national eID scheme. eID schemes are switched on market by market — call `GET /api/v1/helpers/signature-methods` for the set your account can actually use rather than hard-coding a list - `twoStepVerification` - identity gate passed BEFORE the document opens: `NONE` (default), `PIN_BEFORE_SIGNING`, `SMS_BEFORE_SIGNING`, `EMAIL_BEFORE_SIGNING`, or an eID gate such as `BANKID_BEFORE_SIGNING` — call `GET /api/v1/helpers/two-step-verifications` for the live list **Complete Workflow with Templates:** 1. **Create template** (manually in dashboard) with FORM fields containing keys (e.g., "name", "phone", "email") 2. **Create document from template** (this endpoint) - include parties with their `deliveryMethod` and `requiredSignature` settings 3. **Fill form fields** using key-based updates: `PATCH /api/v1/documents/{docId}/fields/key:name` 4. **Add more parties** if needed: `POST /api/v1/documents/{docId}/parties` 5. **Send for signing**: `POST /api/v1/documents/{docId}/send` **Note:** Each party can have their own `deliveryMethod` (EMAIL, SMS, NONE) and `requiredSignature` (DRAWING, BANKID, CLICK_TO_SIGN) configured when adding them. **Example workflow:** ```json # Step 1: Create document from template with parties POST /api/v1/documents { "name": "Employment Contract", "templateId": "template-id-with-form-fields", "parties": [ { "type": "contact", "contactId": "contact-456", "role": "SIGNER", "deliveryMethod": "EMAIL", "requiredSignature": "BANKID" } ] } # Step 2: Fill form fields using keys PATCH /api/v1/documents/{docId}/fields/key:name { "fieldMeta": {"type": "input", "value": "Andreas"} } PATCH /api/v1/documents/{docId}/fields/key:phone { "fieldMeta": {"type": "input", "value": "0767767712"} } # Step 3: Send for signing POST /api/v1/documents/{docId}/send {} ``` **Response:** Returns the created document ID, party IDs, tokens, and signing URLs for all added parties. The legacy `signers` field is also included in the response (same content as `parties`) for backwards compatibility, but is deprecated. 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 post /api/v1/documents 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: post: summary: Create a new document description: >- Create a new document in DRAFT status. You can optionally include parties, metadata, and responsible user during creation. **Document Types:** - `SIGNABLE` (default) - Standard signing document - `ACCEPTABLE` - Document that requires acceptance rather than signature - `ARCHIVE_IMPORTED` - Imported from external archive **Template Support:** Use `templateId` to create a document from a template. Template fields and template parties are automatically copied unless `parties` are explicitly provided in the request. **CRM Link:** Use `integrationLink` to link the document to a CRM record (currently HubSpot deals). When the workspace has a field mapping configured for the integration, mapped custom fields and product-table rows are prefilled from the record, and signing status is written back to it. Explicit `customFields` in the request take precedence over prefilled values. **Responsible User:** Use `responsibleUserId` to assign a specific team member as responsible for the document. Defaults to the creating user if not specified. **Adding Parties:** Two approaches are supported: 1. **Contact-based** (recommended): Provide `contactId` to reference existing contacts - automatically inherits all contact details 2. **Manual**: Provide `name` and `email` to manually specify party details > **Note:** The legacy `signers` field is also accepted as input for backwards compatibility, but is deprecated and will stop working in API v2. Use `parties` going forward. If both are provided, `parties` takes precedence. **Party Examples:** ```json { "parties": [ { "contactId": "contact-123", "role": "SIGNER", "signingOrder": 1, "deliveryMethod": "EMAIL", "requiredSignature": "BANKID" }, { "name": "John Doe", "email": "john@example.com", "role": "SIGNER", "signingOrder": 2, "deliveryMethod": "SMS", "requiredSignature": "DRAWING" } ] } ``` **Per-Party Settings:** - `deliveryMethod` - How to notify: `EMAIL` (default), `SMS`, or `NONE` - `requiredSignature` - Signature type: `DRAWING`, `BANKID` (Swedish BankID), `CLICK_TO_SIGN`, `MANUAL`, or a national eID scheme. eID schemes are switched on market by market — call `GET /api/v1/helpers/signature-methods` for the set your account can actually use rather than hard-coding a list - `twoStepVerification` - identity gate passed BEFORE the document opens: `NONE` (default), `PIN_BEFORE_SIGNING`, `SMS_BEFORE_SIGNING`, `EMAIL_BEFORE_SIGNING`, or an eID gate such as `BANKID_BEFORE_SIGNING` — call `GET /api/v1/helpers/two-step-verifications` for the live list **Complete Workflow with Templates:** 1. **Create template** (manually in dashboard) with FORM fields containing keys (e.g., "name", "phone", "email") 2. **Create document from template** (this endpoint) - include parties with their `deliveryMethod` and `requiredSignature` settings 3. **Fill form fields** using key-based updates: `PATCH /api/v1/documents/{docId}/fields/key:name` 4. **Add more parties** if needed: `POST /api/v1/documents/{docId}/parties` 5. **Send for signing**: `POST /api/v1/documents/{docId}/send` **Note:** Each party can have their own `deliveryMethod` (EMAIL, SMS, NONE) and `requiredSignature` (DRAWING, BANKID, CLICK_TO_SIGN) configured when adding them. **Example workflow:** ```json # Step 1: Create document from template with parties POST /api/v1/documents { "name": "Employment Contract", "templateId": "template-id-with-form-fields", "parties": [ { "type": "contact", "contactId": "contact-456", "role": "SIGNER", "deliveryMethod": "EMAIL", "requiredSignature": "BANKID" } ] } # Step 2: Fill form fields using keys PATCH /api/v1/documents/{docId}/fields/key:name { "fieldMeta": {"type": "input", "value": "Andreas"} } PATCH /api/v1/documents/{docId}/fields/key:phone { "fieldMeta": {"type": "input", "value": "0767767712"} } # Step 3: Send for signing POST /api/v1/documents/{docId}/send {} ``` **Response:** Returns the created document ID, party IDs, tokens, and signing URLs for all added parties. The legacy `signers` field is also included in the response (same content as `parties`) for backwards compatibility, but is deprecated. operationId: createDocument parameters: - name: authorization in: header description: Bearer token for API authentication required: true schema: type: string - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Makes retries safe. A retry with the same key and the same request replays the stored response for 24 hours (header `Idempotent-Replayed: true`); the same key with a different request returns 400. requestBody: description: Body content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Document name/title externalId: description: Your external reference ID for tracking this document type: string nullable: true expiresAt: description: Expiration date for the document nullable: true type: string format: date-time type: description: >- Document type: SIGNABLE (default), ACCEPTABLE, or ARCHIVE_IMPORTED type: string enum: - SIGNABLE - ACCEPTABLE - ARCHIVE_IMPORTED templateId: description: >- Template ID to create document from. Template fields and template parties are copied by default. type: string nullable: true responsibleUserId: description: >- User ID of the person responsible for this document. Must be a member of your organization. Defaults to the creating user. type: string documentMeta: description: >- Document metadata including subject, message, signing order, etc. type: object properties: subject: description: Email subject line when sending document type: string message: description: Custom message included in signing invitation type: string signingOrder: description: >- Signing order: PARALLEL (all signers can sign simultaneously) or SEQUENTIAL (signers must sign in order) type: string enum: - PARALLEL - SEQUENTIAL forceReadFullDocument: description: >- Whether signers must read the entire document before signing type: boolean showChatToSigners: description: Whether to show document chat to signers type: boolean preferredLanguage: description: >- Preferred language for the signing interface: sv (Swedish), en (English), no (Norwegian), da (Danish), or fi (Finnish) type: string enum: - sv - en - 'no' - da - fi - de - is - es - fr - it value: description: Monetary value of the document (for contracts) type: string redirectUrl: description: >- URL to redirect signers to after signing is complete. Must be http(s). type: string redirectEnabled: description: Whether redirect after signing is enabled type: boolean internalRecipients: description: >- Email addresses that receive a copy of the sealed PDF once the document is completed (max 5). Pass an empty array to clear. maxItems: 5 type: array items: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ signableAfterExpired: description: >- Whether the document remains signable after its expiration date type: boolean sendPlainTextEmailOnly: description: >- Send plain text email invitations only (no HTML). null inherits the workspace default. type: boolean nullable: true reminderIntervalDays: description: Days between automatic reminders type: string nullable: true allowDelegation: description: Whether signers may delegate signing to another person type: boolean accessVerification: description: >- Document-wide verification required to open: NONE (default), SMS_BEFORE_SIGNING, EMAIL_BEFORE_SIGNING, or BANKID_BEFORE_SIGNING type: string enum: - NONE - SMS_BEFORE_SIGNING - EMAIL_BEFORE_SIGNING - PIN_BEFORE_SIGNING - SE_BANKID_BEFORE_SIGNING - NO_BANKID_BIOMETRIC_BEFORE_SIGNING - NO_BANKID_HIGH_BEFORE_SIGNING - DK_MITID_BEFORE_SIGNING - DK_MITID_ERHVERV_BEFORE_SIGNING - FI_FTN_BEFORE_SIGNING - NL_IDIN_BEFORE_SIGNING aiChatEnabled: description: >- Whether the signer-facing AI chat is enabled. null inherits the workspace default. type: boolean nullable: true ssnDisplayMode: description: >- How personal numbers are displayed to signers: FULL, PARTIAL, or NONE. null inherits the workspace default. type: string enum: - FULL - PARTIAL - NONE nullable: true sameDeviceSigning: description: Whether all parties sign in sequence on one device type: boolean documentCategoryId: description: >- Document category (Dokumenttyp) ID. See GET /api/v1/document-categories. type: string nullable: true additionalProperties: false documentStyle: description: >- Document styling configuration including orientation, padding, background, and layout type: object properties: orientation: description: 'Document orientation: PORTRAIT (default) or LANDSCAPE' type: string enum: - PORTRAIT - LANDSCAPE paddingEnabled: description: >- Whether to show padding around document content. When false, content fills entire page edge-to-edge (default: true) type: boolean backgroundColor: description: >- Background color for the document in hex format (e.g., #ffffff for white, #000000 for black). Default: #ffffff type: string pattern: ^#[0-9A-Fa-f]{6}$ backgroundOpacity: description: 'Opacity of the background color (0-1). Default: 1' type: number minimum: 0 maximum: 1 backgroundImageUrl: description: URL for the background image type: string nullable: true backgroundImageSize: description: >- Background image sizing: FILL, FIT, or ORIGINAL. Default: FILL type: string enum: - FILL - FIT - ORIGINAL backgroundImagePosition: description: 'Background image position. Default: CENTER' type: string enum: - TOP_LEFT - TOP_CENTER - TOP_RIGHT - CENTER_LEFT - CENTER - CENTER_RIGHT - BOTTOM_LEFT - BOTTOM_CENTER - BOTTOM_RIGHT backgroundImageRepeat: description: >- Background image repeat: REPEAT or NO_REPEAT. Default: NO_REPEAT type: string enum: - REPEAT - NO_REPEAT backgroundImageOpacity: description: 'Opacity of the background image (0-1). Default: 1' type: number minimum: 0 maximum: 1 pageSize: description: 'Page size: A4 (default), A3, or SLIDE' type: string enum: - A4 - A3 - SLIDE theme: description: >- Document theme: body and heading fonts, text, heading and accent colors, density and text size. null resets to the default theme. type: object properties: bodyFont: type: string enum: - inter - arial - roboto - open-sans - lato - montserrat - ibm-plex-sans - georgia - merriweather - lora - source-serif - playfair headingFont: type: string enum: - inter - arial - roboto - open-sans - lato - montserrat - ibm-plex-sans - georgia - merriweather - lora - source-serif - playfair textColor: type: string pattern: ^#[0-9a-fA-F]{6}$ headingColor: type: string pattern: ^#[0-9a-fA-F]{6}$ accentColor: type: string pattern: ^#[0-9a-fA-F]{6}$ density: type: string enum: - compact - normal - relaxed textSize: type: string enum: - sm - md - lg additionalProperties: false nullable: true additionalProperties: false signers: default: [] description: >- **[DEPRECATED — use `parties` instead, will be removed in API v2]** Array of signers to add to the document during creation. If both `signers` and `parties` are provided, `parties` takes precedence. type: array items: anyOf: - type: object properties: contactId: type: string minLength: 1 description: ID of existing contact to add as a party role: default: SIGNER description: >- Party role: SIGNER, ORGANIZER, or REVIEWER. (ACCEPTOR is deprecated and treated as SIGNER.) signingOrder: description: >- Order for sequential signing (1, 2, 3, etc.). Ignored for parallel signing. type: number deliveryMethod: description: >- Per-party delivery method: EMAIL (default), SMS, or NONE (manual link sharing) type: string enum: - EMAIL - SMS - NONE - IN_APP requiredSignature: description: >- Per-party signature type: DRAWING, BANKID, or CLICK_TO_SIGN. Defaults to organization settings. type: string enum: - NONE - DRAWING - SE_BANKID - MANUAL - CLICK_TO_SIGN - NO_BANKID_BIOMETRIC - NO_BANKID_HIGH - NO_QES - DK_MITID - DK_MITID_ERHVERV - FI_FTN - NL_IDIN twoStepVerification: description: >- Per-party 2FA: NONE (default), SMS_BEFORE_SIGNING, EMAIL_BEFORE_SIGNING, or BANKID_BEFORE_SIGNING type: string enum: - NONE - SMS_BEFORE_SIGNING - EMAIL_BEFORE_SIGNING - PIN_BEFORE_SIGNING - SE_BANKID_BEFORE_SIGNING - NO_BANKID_BIOMETRIC_BEFORE_SIGNING - NO_BANKID_HIGH_BEFORE_SIGNING - DK_MITID_BEFORE_SIGNING - DK_MITID_ERHVERV_BEFORE_SIGNING - FI_FTN_BEFORE_SIGNING - NL_IDIN_BEFORE_SIGNING required: - contactId - role additionalProperties: false - type: object properties: name: type: string minLength: 1 description: Party full name email: type: string minLength: 1 format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: Party email address role: default: SIGNER description: >- Party role: SIGNER, ORGANIZER, or REVIEWER. (ACCEPTOR is deprecated and treated as SIGNER.) signingOrder: description: >- Order for sequential signing (1, 2, 3, etc.). Ignored for parallel signing. type: number companyName: description: >- Company name (required if companyOrgNumber is provided) type: string companyRole: description: >- Role/title within the company (e.g. CEO, Board member) type: string companyOrgNumber: description: >- Company organization number (required if companyName is provided) type: string country: description: >- ISO 3166-1 alpha-3 country code for the party (e.g. SWE, USA, DEU) type: string deliveryMethod: description: >- Per-party delivery method: EMAIL (default), SMS, or NONE (manual link sharing) type: string enum: - EMAIL - SMS - NONE - IN_APP requiredSignature: description: >- Per-party signature type: DRAWING, BANKID, or CLICK_TO_SIGN. Defaults to organization settings. type: string enum: - NONE - DRAWING - SE_BANKID - MANUAL - CLICK_TO_SIGN - NO_BANKID_BIOMETRIC - NO_BANKID_HIGH - NO_QES - DK_MITID - DK_MITID_ERHVERV - FI_FTN - NL_IDIN twoStepVerification: description: >- Per-party 2FA: NONE (default), SMS_BEFORE_SIGNING, EMAIL_BEFORE_SIGNING, or BANKID_BEFORE_SIGNING type: string enum: - NONE - SMS_BEFORE_SIGNING - EMAIL_BEFORE_SIGNING - PIN_BEFORE_SIGNING - SE_BANKID_BEFORE_SIGNING - NO_BANKID_BIOMETRIC_BEFORE_SIGNING - NO_BANKID_HIGH_BEFORE_SIGNING - DK_MITID_BEFORE_SIGNING - DK_MITID_ERHVERV_BEFORE_SIGNING - FI_FTN_BEFORE_SIGNING - NL_IDIN_BEFORE_SIGNING required: - name - email - role additionalProperties: false parties: default: [] description: >- Array of parties to add to the document during creation. Provide either contactId to reference existing contacts, or name and email to manually specify party details. type: array items: anyOf: - type: object properties: contactId: type: string minLength: 1 description: ID of existing contact to add as a party role: default: SIGNER description: >- Party role: SIGNER, ORGANIZER, or REVIEWER. (ACCEPTOR is deprecated and treated as SIGNER.) signingOrder: description: >- Order for sequential signing (1, 2, 3, etc.). Ignored for parallel signing. type: number deliveryMethod: description: >- Per-party delivery method: EMAIL (default), SMS, or NONE (manual link sharing) type: string enum: - EMAIL - SMS - NONE - IN_APP requiredSignature: description: >- Per-party signature type: DRAWING, BANKID, or CLICK_TO_SIGN. Defaults to organization settings. type: string enum: - NONE - DRAWING - SE_BANKID - MANUAL - CLICK_TO_SIGN - NO_BANKID_BIOMETRIC - NO_BANKID_HIGH - NO_QES - DK_MITID - DK_MITID_ERHVERV - FI_FTN - NL_IDIN twoStepVerification: description: >- Per-party 2FA: NONE (default), SMS_BEFORE_SIGNING, EMAIL_BEFORE_SIGNING, or BANKID_BEFORE_SIGNING type: string enum: - NONE - SMS_BEFORE_SIGNING - EMAIL_BEFORE_SIGNING - PIN_BEFORE_SIGNING - SE_BANKID_BEFORE_SIGNING - NO_BANKID_BIOMETRIC_BEFORE_SIGNING - NO_BANKID_HIGH_BEFORE_SIGNING - DK_MITID_BEFORE_SIGNING - DK_MITID_ERHVERV_BEFORE_SIGNING - FI_FTN_BEFORE_SIGNING - NL_IDIN_BEFORE_SIGNING required: - contactId - role additionalProperties: false - type: object properties: name: type: string minLength: 1 description: Party full name email: type: string minLength: 1 format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: Party email address role: default: SIGNER description: >- Party role: SIGNER, ORGANIZER, or REVIEWER. (ACCEPTOR is deprecated and treated as SIGNER.) signingOrder: description: >- Order for sequential signing (1, 2, 3, etc.). Ignored for parallel signing. type: number companyName: description: >- Company name (required if companyOrgNumber is provided) type: string companyRole: description: >- Role/title within the company (e.g. CEO, Board member) type: string companyOrgNumber: description: >- Company organization number (required if companyName is provided) type: string country: description: >- ISO 3166-1 alpha-3 country code for the party (e.g. SWE, USA, DEU) type: string deliveryMethod: description: >- Per-party delivery method: EMAIL (default), SMS, or NONE (manual link sharing) type: string enum: - EMAIL - SMS - NONE - IN_APP requiredSignature: description: >- Per-party signature type: DRAWING, BANKID, or CLICK_TO_SIGN. Defaults to organization settings. type: string enum: - NONE - DRAWING - SE_BANKID - MANUAL - CLICK_TO_SIGN - NO_BANKID_BIOMETRIC - NO_BANKID_HIGH - NO_QES - DK_MITID - DK_MITID_ERHVERV - FI_FTN - NL_IDIN twoStepVerification: description: >- Per-party 2FA: NONE (default), SMS_BEFORE_SIGNING, EMAIL_BEFORE_SIGNING, or BANKID_BEFORE_SIGNING type: string enum: - NONE - SMS_BEFORE_SIGNING - EMAIL_BEFORE_SIGNING - PIN_BEFORE_SIGNING - SE_BANKID_BEFORE_SIGNING - NO_BANKID_BIOMETRIC_BEFORE_SIGNING - NO_BANKID_HIGH_BEFORE_SIGNING - DK_MITID_BEFORE_SIGNING - DK_MITID_ERHVERV_BEFORE_SIGNING - FI_FTN_BEFORE_SIGNING - NL_IDIN_BEFORE_SIGNING required: - name - email - role additionalProperties: false customFields: description: Custom field values for the document type: array items: type: object properties: customInputId: type: string minLength: 1 value: type: string nullable: true required: - customInputId - value additionalProperties: false integrationLink: description: >- Link the document to a CRM record. Prefills mapped custom fields and product tables from the record (configured under Integrations) and enables status write-back to it. type: object properties: integration: type: string description: >- Which connected integration the record belongs to. Currently only hubspot. enum: - hubspot type: type: string description: External record type. Currently only deal. enum: - deal id: type: string minLength: 1 description: The external record ID, e.g. the HubSpot deal ID. required: - integration - type - id additionalProperties: false required: - name - signers - parties additionalProperties: false responses: '200': description: '200' content: application/json: schema: type: object properties: documentId: type: string description: Unique identifier for the created document externalId: description: Your external reference ID type: string nullable: true expiresAt: description: Document expiration date nullable: true type: string format: date-time signers: type: array items: type: object properties: signerId: type: string description: Unique identifier for this party name: type: string description: Party full name email: description: Party email address type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ nullable: true role: type: string enum: - SIGNER - ORGANIZER - REVIEWER description: Party role signingOrder: description: Signing order (for sequential signing) type: number nullable: true type: type: string enum: - INDIVIDUAL - COMPANY description: 'Party type: INDIVIDUAL or COMPANY' companyName: description: Company name (for company parties) type: string nullable: true companyRole: description: Role/title within the company type: string nullable: true companyOrgNumber: description: Company organization number (for company parties) type: string nullable: true country: description: >- ISO 3166-1 alpha-3 country code for the party (e.g. SWE) type: string nullable: true contactId: description: >- Contact ID if this party was created from an existing contact type: string nullable: true required: - signerId - name - role - type additionalProperties: false description: >- **[DEPRECATED — use `parties` instead, will be removed in API v2]** Array of created parties. Same content as `parties`. parties: type: array items: type: object properties: signerId: type: string description: Unique identifier for this party name: type: string description: Party full name email: description: Party email address type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ nullable: true role: type: string enum: - SIGNER - ORGANIZER - REVIEWER description: Party role signingOrder: description: Signing order (for sequential signing) type: number nullable: true type: type: string enum: - INDIVIDUAL - COMPANY description: 'Party type: INDIVIDUAL or COMPANY' companyName: description: Company name (for company parties) type: string nullable: true companyRole: description: Role/title within the company type: string nullable: true companyOrgNumber: description: Company organization number (for company parties) type: string nullable: true country: description: >- ISO 3166-1 alpha-3 country code for the party (e.g. SWE) type: string nullable: true contactId: description: >- Contact ID if this party was created from an existing contact type: string nullable: true required: - signerId - name - role - type additionalProperties: false description: >- Array of created parties. Use GET /documents/:id/parties/:partyId to retrieve signing URLs. required: - documentId - signers - parties 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 '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: - documents:write 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.