Signing Widget

Signeum provides a signing widget that handles the complete signing experience — PDF viewing, signature capture, form fields, BankID authentication, OTP verification, and chat. There are two ways to use it:

Both modes use the same signing token and support all signing methods (drawn, typed, BankID), project branding, and real-time status updates.

Hosted Signing Page

The simplest integration. When you create a document via the API, the response includes a signingUrls array with a unique URL per participant. Redirect or link the signer to their URL — Signeum handles everything else.

{
  "signingUrls": [
    {
      "participantId": "p1a2b3c4-...",
      "name": "Anna Lindström",
      "email": "[email]",
      "role": "signer",
      "signingUrl": "https://app.signeum.se/sign/abc123def456..."
    }
  ]
}

The hosted page automatically applies your project's branding (logo, colors, company name) and handles the full signing flow including post-signing behavior.

Embedded Widget

For a seamless in-app experience, load the Signeum widget script and mount it in a container element on your page. The widget renders the full signing UI inside your application.

1. Include the script and stylesheet

<link rel="stylesheet" href="https://cdn.signeum.se/signeum-widget.css">
<script type="module">
  import { init } from 'https://cdn.signeum.se/signeum-widget.js';

  const widget = init({
    containerId: 'signeum-widget',
    token: 'abc123def456...',
    onComplete: (result) => {
      console.log('Signed!', result.documentId, result.status);
    },
    onError: (error) => {
      console.error('Error:', error.code, error.message);
    },
  });

  // To unmount later:
  // widget.destroy();
</script>

2. Add a container element

<div id="signeum-widget" style="width: 100%; height: 700px;"></div>

Options

The init() function returns an object with a destroy() method to unmount the widget and clean up resources.

Integration Flow

Regardless of which mode you choose, the integration follows the same pattern:

1. Create a document via the REST API
   POST /organizations/:orgId/projects/:projectId/documents
   → Response includes signingUrls with a token per participant

2. Present the signing experience
   Option A: Redirect signer to the signingUrl (hosted page)
   Option B: Extract the token and pass it to the embedded widget

3. Signer completes the flow
   The widget handles PDF viewing, signature capture, fields,
   BankID, OTP, and submission

4. Receive status updates
   Via webhook (configured on project level) or the onComplete callback (embedded)
   Or poll GET /documents/:id for status

Extracting the token from a signing URL

If you're using the embedded widget, you need the token from the signing URL. The token is the last path segment:

const signingUrl = "https://app.signeum.se/sign/abc123def456...";
const token = signingUrl.split('/sign/')[1];
// → "abc123def456..."

Customization

The widget's appearance is controlled by project settings. Configure these in the Signeum dashboard or via the API. All customization applies to both hosted and embedded modes.

Branding

Feature toggles

Callbacks & Events

There are two ways to track what happens during and after signing:

Widget callbacks (embedded mode)

The onComplete and onError callbacks fire in the browser when the participant finishes or encounters an error.

init({
  containerId: 'signeum-widget',
  token: signingToken,
  onComplete: (result) => {
    // result.documentId — the document UUID
    // result.status — "completed" when all have signed
    showSuccessMessage();
  },
  onError: (error) => {
    // error.code — e.g. "EXPIRED", "CANCELLED"
    // error.message — human-readable description
    showErrorMessage(error.message);
  },
});

Webhooks (server-side)

For reliable server-to-server notifications, configure a callbackUrl in your project settings. Signeum sends POST requests for all document lifecycle events, for documents created both via the API and the UI. See the Webhooks section in the API docs for the full event list and payload format.

Post-signing Behavior

Control what happens after a participant signs. This is configured at the project level and applies to the hosted signing page.

For the embedded widget, use the onComplete callback to control the post-signing experience in your own application.