API Documentation

Signeum's REST API lets you integrate legally binding document signing directly into your product. Create documents, manage signers, and track status — all through the API.

Base URL

https://api.signeum.se/api/v1

All requests and responses use JSON. Always include the header Content-Type: application/json.

Widget integration?

If you're looking to embed the signing experience in your application, see the Widget Guide.

Concepts & Data Model

Before you start integrating, it helps to understand how Signeum is structured. Here are the core concepts and how they relate to each other.

Organization → Project → Document

Signeum's data model has three levels. An organization is your account and owns all resources. Within the organization, projects group documents and carry settings for branding, signing methods, and notifications. Documents are always created within a project and inherit the project's settings.

Default Projects

Every new organization automatically gets two system projects:

Standard Signing — supports methods drawn, typed, and none (simple e-signature)
eID Signing — configured for bankid_se (Swedish BankID)

You can create your own projects with custom settings via the API.

Signing Methods

A project uses either standard methods (drawn, typed, none) or eID (bankid_se). You cannot mix standard and eID methods in the same project. For eID projects, signers must have a personalNumber (Swedish personal number).

Project Settings

Each project has settings that affect all documents within it:

Branding — logo, colors, and company name in the signing view
Email notifications — can be enabled or disabled per project
Chat — allow participants to communicate in the signing view
Audit log — embed the audit trail in the signed PDF
Post-signing — show a message or redirect to a URL after signing
Auto-reminder — send a reminder after N days

Document Status

A document goes through the following statuses during its lifecycle:

Status	Description
`pending`	The document is created and waiting for the first signer to act
`in_progress`	At least one signer has signed, but not all
`completed`	All signers have signed — the document is complete
`expired`	The signing deadline has passed without all signatures
`cancelled`	The document has been cancelled by the sender
`declined`	A signer has declined to sign

Multi-tenant Pattern

If you're building a SaaS product and want to offer signing to your customers, you can create one project per customer (tenant). Each project can have its own logo, colors, and company name — so the signing view matches the customer's brand.

White-label Email

Want to send your own emails instead of Signeum's default notifications? Disable email notifications at the project level and listen to webhook events (e.g. document.completed, document.signed). Then send your own emails with your sender address and design.

Signing Order

Participants can be assigned a signingOrder. Signers with a lower order number must sign before the next in line gets access to the document. Participants with the same order number can sign in parallel.

Authentication

All API calls require a valid API key. Keys are created in the organization settings by an owner. Each key is scoped to one organization.

API keys are prefixed with ds_ and sent via the Authorization header:

HEADER Authorization header

Authorization: Bearer ds_your_api_key_here

The API key is only shown once at creation time. Store it securely. If you lose it, you'll need to create a new one.

Rate Limiting

The API allows 100 requests per minute per API key. If the limit is exceeded, status code 429 Too Many Requests is returned.

The response includes a Retry-After header with the number of seconds until the window resets.

Error Handling

All errors are returned with a consistent JSON structure:

ERROR Error format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "trackingId": "abc-123-def",
    "details": {
      "fields": {
        "name": "Document name is required"
      }
    }
  }
}

Status Code	Code	Description
400	VALIDATION_ERROR	Invalid request or validation error
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Access denied to the resource
404	NOT_FOUND	Resource not found
402	PAYMENT_REQUIRED	Payment method required
429	RATE_LIMITED	Rate limit exceeded
500	INTERNAL_ERROR	Internal server error

Webhooks

Provide a callbackUrl when creating a document to receive real-time notifications about document events. Signeum sends a POST request with a JSON payload to your URL.

POST Webhook payload

{
  "eventType": "document.signed",
  "timestamp": "2026-03-16T10:30:00Z",
  "documentId": "d4f5a6b7-...",
  "organizationId": "a1b2c3d4-...",
  "projectId": "e5f6a7b8-...",
  "participant": {
    "name": "Anna Lindström",
    "email": "[email]",
    "role": "signer"
  }
}

Event	Description
document.viewed	A signer has opened the document
document.signed	A signer has signed the document
document.reviewed	A reviewer has reviewed the document
document.completed	All signers have signed — the document is complete
document.cancelled	The document has been cancelled
document.expired	The signing deadline has passed
document.declined	A signer has declined to sign
chat.message	A new chat message on the document

POST /organizations/:orgId/projects

Create a new project in the organization. Projects are used to group documents and can have separate settings for branding, signing methods, and notifications.

Parameters

Parameter	Type	Required	Description
name	string	Yes	Project name (1–255 characters)

POST Example request

curl -X POST https://api.signeum.se/api/v1/organizations/{orgId}/projects \
  -H "Authorization: Bearer ds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Customer Contracts" }'

201 Response

{
  "project": {
    "id": "e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9",
    "organizationId": "a1b2c3d4-...",
    "name": "Customer Contracts",
    "isDefault": false,
    "createdAt": "2026-03-16T10:00:00Z",
    "updatedAt": "2026-03-16T10:00:00Z",
    "settings": {
      "emailNotificationsEnabled": true,
      "includeAuditInDocument": true,
      "chatEnabled": true,
      "allowedSigningMethods": ["drawn", "typed", "none", "bankid_se"]
    }
  }
}

GET /organizations/:orgId/projects

List all projects in the organization with pagination.

Query parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)
search	string	Search by project name
sort	string	Sort order, e.g. `createdAt:desc`

GET Example request

curl https://api.signeum.se/api/v1/organizations/{orgId}/projects \
  -H "Authorization: Bearer ds_your_api_key"

200 Response

{
  "projects": [
    {
      "id": "e5f6a7b8-...",
      "organizationId": "a1b2c3d4-...",
      "name": "Customer Contracts",
      "isDefault": false,
      "createdAt": "2026-03-16T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

GET /organizations/:orgId/projects/:projectId

Get details for a specific project including settings.

GET Example request

curl https://api.signeum.se/api/v1/organizations/{orgId}/projects/{projectId} \
  -H "Authorization: Bearer ds_your_api_key"

POST /organizations/:orgId/projects/:projectId/documents

Create a new document with participants and send it for signing. The document can be uploaded as a base64-encoded PDF, fetched from a URL, or created from a template.

Parameters

Parameter	Type	Required	Description
name	string	Yes	Document name (1–255 characters)
document	object	Yes*	PDF upload. Either `{ type: "base64", content: "..." }` or `{ type: "url", url: "..." }`
templateId	string	Yes*	UUID of a template to create the document from. Alternative to `document`
participants	array	Yes	List of participants (1–50). See participant object below
signingDeadline	string	No	ISO 8601 date. Max 30 days ahead
callbackUrl	string	No	Webhook URL for status updates
allowedSigningMethods	array	No	Allowed signing methods: `drawn`, `typed`, `none`. Ignored for eID projects (BankID is configured at the project level)
autoReminderDays	number	No	Send automatic reminder after N days (1–30)
roleMapping	object	No	Mapping of template roles to participants (for template-based creation)

* Either document or templateId must be provided.

Participant object

Parameter	Type	Required	Description
name	string	Yes	Participant's name
email	string	Yes	Email address
role	string	Yes	`signer` or `reviewer`
signingOrder	number	No	Signing order (positive integer)
language	string	No	`sv` or `en` (default: `en`)
otpEnabled	boolean	No	Require OTP verification via email (default: false)
personalNumber	string	No	Swedish personal number (12 digits, YYYYMMDDXXXX). Required for signers in eID projects (BankID)

POST Example request

curl -X POST https://api.signeum.se/api/v1/organizations/{orgId}/projects/{projectId}/documents \
  -H "Authorization: Bearer ds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement 2026",
    "document": {
      "type": "base64",
      "content": "JVBERi0xLjQK..."
    },
    "participants": [
      {
        "name": "Anna Lindström",
        "email": "[email]",
        "role": "signer",
        "signingOrder": 1,
        "language": "sv"
      },
      {
        "name": "Erik Johansson",
        "email": "[email]",
        "role": "signer",
        "signingOrder": 2,
        "language": "sv"
      }
    ],
    "signingDeadline": "2026-04-15T23:59:59Z",
    "callbackUrl": "https://your-app.com/webhooks/signeum"
  }'

201 Response

{
  "document": {
    "id": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
    "projectId": "e5f6a7b8-...",
    "organizationId": "a1b2c3d4-...",
    "name": "Service Agreement 2026",
    "status": "pending",
    "createdAt": "2026-03-16T10:00:00Z"
  },
  "participants": [
    {
      "id": "p1a2b3c4-...",
      "name": "Anna Lindström",
      "email": "[email]",
      "role": "signer",
      "signingOrder": 1,
      "status": "pending"
    }
  ],
  "signingUrls": [
    {
      "participantId": "p1a2b3c4-...",
      "name": "Anna Lindström",
      "email": "[email]",
      "role": "signer",
      "signingUrl": "https://app.signeum.se/sign/abc123..."
    }
  ]
}

GET /organizations/:orgId/projects/:projectId/documents

List documents in a project with pagination and filtering.

Query parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)
status	string	Filter by status: `pending`, `in_progress`, `completed`, `expired`, `cancelled`
sort	string	Sort order, e.g. `createdAt:desc`

GET Example request

curl https://api.signeum.se/api/v1/organizations/{orgId}/projects/{projectId}/documents?status=pending&limit=10 \
  -H "Authorization: Bearer ds_your_api_key"

GET /organizations/:orgId/documents/:documentId

Get details for a specific document including participants and their status.

GET Example request

curl https://api.signeum.se/api/v1/organizations/{orgId}/documents/{documentId} \
  -H "Authorization: Bearer ds_your_api_key"

200 Response

{
  "document": {
    "id": "d4f5a6b7-...",
    "projectId": "e5f6a7b8-...",
    "organizationId": "a1b2c3d4-...",
    "name": "Service Agreement 2026",
    "status": "in_progress",
    "createdAt": "2026-03-16T10:00:00Z",
    "signingDeadline": "2026-04-15T23:59:59Z"
  },
  "participants": [
    {
      "id": "p1a2b3c4-...",
      "name": "Anna Lindström",
      "email": "[email]",
      "role": "signer",
      "signingOrder": 1,
      "status": "signed",
      "signedAt": "2026-03-16T14:30:00Z",
      "signatureMode": "drawn"
    },
    {
      "id": "p2b3c4d5-...",
      "name": "Erik Johansson",
      "email": "[email]",
      "role": "signer",
      "signingOrder": 2,
      "status": "pending"
    }
  ]
}

PUT /organizations/:orgId/documents/:documentId/cancel

Cancel a document that hasn't been completed yet. All pending signers will be notified.

PUT Example request

curl -X PUT https://api.signeum.se/api/v1/organizations/{orgId}/documents/{documentId}/cancel \
  -H "Authorization: Bearer ds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Agreement needs to be updated" }'

GET /organizations/:orgId/documents/:documentId/download

Get a signed URL to download the signed document (PDF). Available when the document has status completed.

GET Example request

curl https://api.signeum.se/api/v1/organizations/{orgId}/documents/{documentId}/download \
  -H "Authorization: Bearer ds_your_api_key"

200 Response

{
  "downloadUrl": "https://storage.signeum.se/signed/...",
  "expiresAt": "2026-03-16T11:00:00Z"
}

GET /organizations/:orgId/templates

List all templates in the organization.

GET Example request

curl https://api.signeum.se/api/v1/organizations/{orgId}/templates \
  -H "Authorization: Bearer ds_your_api_key"

200 Response

{
  "templates": [
    {
      "id": "t1a2b3c4-...",
      "name": "Employment Agreement",
      "description": "Standard template for employment agreements",
      "signerCount": 2,
      "signerRoles": [
        { "index": 0, "label": "Employer", "role": "signer", "signingOrder": 1 },
        { "index": 1, "label": "Employee", "role": "signer", "signingOrder": 2 }
      ],
      "createdAt": "2026-01-15T08:00:00Z"
    }
  ]
}

GET /organizations/:orgId/templates/:templateId

Get details for a specific template including field definitions and signer roles.

GET Example request

curl https://api.signeum.se/api/v1/organizations/{orgId}/templates/{templateId} \
  -H "Authorization: Bearer ds_your_api_key"

POST /organizations/:orgId/projects/:projectId/documents

Create a document from a template. Provide templateId instead of document and map the template's roles to actual participants with roleMapping.

POST Example request

curl -X POST https://api.signeum.se/api/v1/organizations/{orgId}/projects/{projectId}/documents \
  -H "Authorization: Bearer ds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement — Anna Lindström",
    "templateId": "t1a2b3c4-...",
    "participants": [
      {
        "name": "Acme Corp",
        "email": "[email]",
        "role": "signer",
        "language": "en"
      },
      {
        "name": "Anna Lindström",
        "email": "[email]",
        "role": "signer",
        "language": "sv"
      }
    ],
    "roleMapping": { "0": 0, "1": 1 },
    "callbackUrl": "https://your-app.com/webhooks/signeum"
  }'

roleMapping maps the template's role index (key) to the participant's index in the participants array (value). In the example above, template role 0 maps to participant 0 and template role 1 maps to participant 1.

API Documentation

Concepts & Data Model

Organization → Project → Document

Default Projects

Signing Methods

Project Settings

Document Status

Multi-tenant Pattern

White-label Email

Signing Order

Authentication

Rate Limiting

Error Handling

Webhooks

Projects

POST /organizations/:orgId/projects

Parameters

GET /organizations/:orgId/projects

Query parameters

GET /organizations/:orgId/projects/:projectId

Documents

POST /organizations/:orgId/projects/:projectId/documents

Parameters

Participant object

GET /organizations/:orgId/projects/:projectId/documents

Query parameters

GET /organizations/:orgId/documents/:documentId

PUT /organizations/:orgId/documents/:documentId/cancel

GET /organizations/:orgId/documents/:documentId/download

Templates

GET /organizations/:orgId/templates

GET /organizations/:orgId/templates/:templateId

POST /organizations/:orgId/projects/:projectId/documents