---
title: "Sign"
method: POST
path: "/v1/sign"
tags: ["Signature"]
---

# Sign

`POST /v1/sign`

Sign a PDF or DOCX document with a cryptographic signature.

Send a JSON request body with:
- `document` (required): object containing either `base64` or `url`
- `signer` (required): signer details — `email` and `name` are required; `ip` and `userAgent` are optional and, when provided, are recorded in the audit trail certificate. No other signer fields are accepted; use `metadata` for anything application-specific.
- `auditTrail` (required): array of signing events. Must include at least one `submit` event for e-signature compliance.
- `eventId` (optional): unique identifier for the signing event
- `metadata` (optional): free-form object for application-specific context (tenantId, contractId, etc.)
- `certificate` (optional): `{ enabled: boolean }` — controls whether an audit trail certificate page is appended (default: `true`)

The response returns the signed PDF as base64.

## Request body

- SignRequest
  - `eventId` string — Unique identifier for this signing event
  - `document` union, required — PDF or DOCX input. Provide exactly one of `base64` or `url`.
    - object
      - `base64` string, byte, required — Base64-encoded PDF or DOCX file
    - object
      - `url` string, uri, required — URL to fetch the document from
  - `signer` object, required — Details of the person applying the signature. `email` and `name` are required; `ip` and `userAgent` are optional and recorded in the audit trail / certificate page when provided. No other fields are accepted — use `metadata` for application-specific context.
    - `email` string, email, required — Signer's email address
    - `name` string, required — Signer's full name as it should appear on the signature
    - `ip` string, ipv4 — IPv4 address the signer submitted from. Included in the audit trail certificate for compliance.
    - `userAgent` string — Browser user agent string the signer submitted from. Included in the audit trail certificate for compliance.
  - `auditTrail` object[], required — Complete event trail of user interactions. Must include at least one `submit` event for e-signature compliance.
    - `type` 'ready' | 'scroll' | 'field_change' | 'submit', required — Event kind
    - `timestamp` string, date-time, required — ISO-8601 timestamp for the event
    - `data` object — Event-specific payload emitted by the e-sign SDK. Shape depends on `type`: - `scroll` - `{ percent: number }` - `field_change` - `{ fieldId: string, value: string | boolean | number | null, previousValue?: string | boolean | number | null }` - `ready`, `submit` - typically omitted
  - `metadata` object — Optional application-specific metadata. Free-form object for any context you want to attach to the signing event (e.g. tenantId, contractId, custom audit fields).
  - `certificate` object — Configuration for the audit trail certificate page that is appended to the signed PDF.
    - `enabled` boolean — Whether to append an audit trail certificate page to the signed document

## Response `200`

Default Response

- SignResponse
  - `document` object, required
    - `base64` string, required — Signed PDF as base64
    - `contentType` string, required — Content type (application/pdf)

## Other responses

- `400` — Standard error format used across all API endpoints
- `401` — Standard error format used across all API endpoints
- `422` — Standard error format used across all API endpoints
- `500` — Standard error format used across all API endpoints

## Changes

- **2026-04-23** `e99d64bcad01` — 3 breaking, 4 info
  - added the new required request property `signer/email`
  - added the new required request property `signer/name`
  - the `auditTrail` request property's minItems was increased to `1`
  - added the new optional request property `certificate`
  - …3 more

[Change history](https://skmtc.dev/superdoc-dev/apis/superdoc-api/changes/v1/sign/post.md)

---

[API](https://skmtc.dev/superdoc-dev/apis/superdoc-api.md) · [All operations](https://skmtc.dev/superdoc-dev/apis/superdoc-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/superdoc-dev/superdoc-api/revisions/869ccb471697/schema)