> ## 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.

# List document categories

> Retrieve every document category (Dokumenttyp) in the workspace, sorted by name.

A category scopes which custom fields apply to a document. Use an `id` from this list as `documentMeta.documentCategoryId` when creating or updating a document, or as `templateMeta.documentCategoryId` on a template.



## OpenAPI

````yaml /api/openapi.json get /api/v1/document-categories
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.


    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/document-categories:
    get:
      summary: List document categories
      description: >-
        Retrieve every document category (Dokumenttyp) in the workspace, sorted
        by name.


        A category scopes which custom fields apply to a document. Use an `id`
        from this list as `documentMeta.documentCategoryId` when creating or
        updating a document, or as `templateMeta.documentCategoryId` on a
        template.
      operationId: getDocumentCategories
      parameters:
        - 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:
                  documentCategories:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique document category identifier
                        name:
                          type: string
                          description: Category name, e.g. "Anställningsavtal"
                        customInputIds:
                          type: array
                          items:
                            type: string
                          description: >-
                            Custom field IDs scoped to this category, in display
                            order. Empty when the category scopes none.
                        createdAt:
                          description: Date and time when the category was created
                          type: string
                          format: date-time
                        updatedAt:
                          description: Date and time when the category was last updated
                          type: string
                          format: date-time
                      required:
                        - id
                        - name
                        - customInputIds
                        - createdAt
                        - updatedAt
                      additionalProperties: false
                required:
                  - documentCategories
                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
                required:
                  - message
                additionalProperties: false
                description: Error response
      security:
        - oauth2:
            - documents:read
        - bearerAuth: []
components:
  securitySchemes:
    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
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Personal API key, e.g. `Authorization: Bearer sajn_sk_...`. Not
        scope-limited — acts as the issuing user.

````