SealRoute API Documentation

Complete REST API reference for integrating SealRoute into your own applications.

Authentication

All API requests require the X-Auth-Token header (unless noted otherwise):

X-Auth-Token: YOUR_API_KEY

Get your API key from Settings → API or via the User Management API.

User Management

List Users

GET /api/users

Returns all active users in the account. Admin only.

Response:

[
  {
    "id": 1,
    "email": "admin@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "admin",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
]

Get Current User

GET /api/user

Returns the authenticated user’s info.

Get User by ID

GET /api/users/:id

Admin only.

Create User

POST /api/users

Admin only. Returns the new user with their API key.

Example:

curl -X POST https://sealroute.com/api/users \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com","first_name":"Jane","role":"editor"}'

Response (201):

{
  "id": 5,
  "email": "new@example.com",
  "first_name": "Jane",
  "last_name": null,
  "role": "editor",
  "api_key": "abc123...generated_key..."
}

Update User

PUT /api/users/:id

Admin only.

Delete User

DELETE /api/users/:id

Admin only. Soft-deletes (archives) the user. Cannot delete yourself.

Get User’s API Key

GET /api/users/:id/api_key

Admin only.

Response:

{
  "id": 5,
  "email": "user@example.com",
  "api_key": "abc123..."
}

Regenerate User’s API Key

POST /api/users/:id/api_key

Admin only. Generates a new API key (old key stops working immediately).

Templates

List Templates

GET /api/templates

Get Template

GET /api/templates/:id

Update Template

PUT /api/templates/:id

Delete Template

DELETE /api/templates/:id

Clone Template

POST /api/templates/:template_id/clone

Submissions

List Submissions

GET /api/submissions

Get Submission

GET /api/submissions/:id

Create Submission

POST /api/submissions

Create a submission from an existing template.

Top-Level Parameters

Submitter-Level Parameters (submitters[])

Create Submission from DOCX

POST /api/submissions/docx

Create a one-off submission from a DOCX file with embedded tags. The DOCX can contain [[variable]] data placeholders and {{Field;type=X}} form field tags. See TEMPLATE_TAGS.md for full tag syntax.

Top-Level Parameters

Submitter-Level Parameters (submitters[])

Variables vs Values

Top-level variables and each submitter’s variables are merged into a single map. Later submitters override duplicate keys.

DOCX Formatting Inheritance

The API automatically carries your Word document’s formatting onto the rendered form fields, so the signed PDF matches the look of your DOCX:

Explicit tag attributes (e.g., font=Courier;font_size=14) override DOCX formatting. For full details see Template Tags → DOCX Formatting Inheritance.

Template Preferences

Both POST /api/submissions and POST /api/submissions/docx accept a top-level preferences object that is persisted on the submission’s template. These flags override account-level defaults (configured under Settings → Personalization) for this specific submission.

Account-level toggles act as a ceiling: if e.g. attach_audit_log is disabled under Personalization, a template-level true here will not re-enable it. The audit trail PDF itself is always generated on completion regardless of these flags; they only control whether it is attached to outgoing emails.

Example

curl -X POST https://sealroute.com/api/submissions/docx \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract",
    "documents": [{"name": "contract.docx", "file": "BASE64_DATA"}],
    "variables": {
      "contract_number": "C-001",
      "contract_date": "April 15, 2026"
    },
    "submitters": [
      {
        "role": "anggota",
        "email": "member@example.com",
        "phone": "+628123456789",
        "variables": {
          "Nama_Anggota": "Muhammad",
          "NRP_Anggota": "1234567890"
        }
      },
      {
        "role": "Buyer",
        "email": "buyer@example.com",
        "name": "John Doe"
      }
    ],
    "order": "preserved",
    "send_email": false,
    "logo_url": "https://example.com/logo.png",
    "company_name": "My Company",
    "preferences": {
      "completed_notification_email_attach_audit": true,
      "documents_copy_email_attach_audit": true
    }
  }'

Response (200): Array of submitter objects with signing URLs:

[
  {
    "id": 1,
    "submission_id": 100,
    "role": "anggota",
    "email": "member@example.com",
    "status": "pending",
    "embed_src": "https://sealroute.com/s/AbCdEf..."
  },
  {
    "id": 2,
    "submission_id": 100,
    "role": "Buyer",
    "email": "buyer@example.com",
    "status": "pending",
    "embed_src": "https://sealroute.com/s/GhIjKl..."
  }
]

e-Meterai (EZMeterai)

Apply Indonesian e-Meterai stamps after all signers complete when the submission opts in. Requires account configuration under Settings → e-Meterai.

Response fields: emeterai_status — pending, stamped, or failed.

Retry stamping:

POST /api/submissions/:id/emeterai

Create Submission from PDF

POST /api/submissions/pdf

Create a submission from a PDF file with text tags.

Delete Submission

DELETE /api/submissions/:id

Get Submission Documents

GET /api/submissions/:id/documents

Returns signed document download URLs.

Response:

{
  "id": 1,
  "documents": [
    { "name": "contract.pdf", "url": "https://..." }
  ]
}

Submitters

List Submitters

GET /api/submitters

Get Submitter

GET /api/submitters/:id

Update Submitter

PUT /api/submitters/:id

Per-API-call White-Label Branding

You can override the SealRoute logo, brand name, and signature stamp image per recipient through the API. Branding sent through the API is scoped strictly to the receiving submitter — it never modifies your account’s Personalization settings, never affects other recipients on the same submission, and never appears on the audit-trail certificate.

Precedence (first non-empty value wins):

1. submitters[].logo_url / company_name / stamp_url — per-recipient (the only API surface)
2. Account Personalization (Settings → Personalization, UI-only)
3. SealRoute defaults

The values flow into:

• The signing page header (logo + brand name) for that recipient
• The post-completion receipt page (/document/:slug/completed) for that recipient
• The signature stamp image rendered into the recipient’s signed copy (stamp_url, then logo_url)

The values do not flow into:

• Account-level Personalization (account_configs) — the API can never write here
• The dashboard / settings UI
• The audit-trail PDF header (always uses account defaults)
• Other recipients on the same submission

Notes:

• Only public URLs are fetched. Non-image responses or redirect loops are silently dropped — the next layer in the chain is used.
• Sending an empty string on PUT /api/submitters/:id clears a previously stored override.
• These overrides are persisted on the submitter record, so reopening the link later still shows the same branding.
• Top-level logo_url / company_name / stamp_url on POST /api/submissions and POST /api/submissions/docx is ignored; supply them inside submitters[] instead.

Tools

Merge PDFs

POST /api/tools/merge

Merge multiple PDF files into one.

Response:

{
  "data": "BASE64_MERGED_PDF"
}

Verify PDF Signature

POST /api/tools/verify

Verify digital signatures in a PDF.

Response:

{
  "checksum_status": "valid",
  "signatures": [...]
}

Webhooks

Manage outgoing webhook URLs that receive HTTP POST callbacks when events occur. Admin only.

Supported Events

List Webhooks

GET /api/webhooks

Response:

{
  "data": [
    {
      "id": 1,
      "url": "https://example.com/webhook",
      "events": ["form.completed", "submission.completed"],
      "secret": { "X-Webhook-Secret": "your_secret" },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "pagination": { "count": 1, "next": 1, "prev": 1 }
}

Get Webhook

GET /api/webhooks/:id

Create Webhook

POST /api/webhooks

Example:

curl -X POST https://sealroute.com/api/webhooks \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["form.completed", "submission.completed"],
    "secret": { "X-Webhook-Secret": "my_secret_token" }
  }'

Response (201):

{
  "id": 1,
  "url": "https://example.com/webhook",
  "events": ["form.completed", "submission.completed"],
  "secret": { "X-Webhook-Secret": "my_secret_token" },
  "created_at": "2026-04-15T10:00:00Z",
  "updated_at": "2026-04-15T10:00:00Z"
}

Update Webhook

PUT /api/webhooks/:id

Delete Webhook

DELETE /api/webhooks/:id

Response:

{
  "message": "Webhook has been deleted"
}

Test Webhook

POST /api/webhooks/:id/test

Sends a test form.completed event using the most recently completed submitter. Useful for verifying your endpoint works.

Response:

{
  "message": "Test webhook request has been queued"
}

Webhook Payload Format

When an event fires, SealRoute sends a POST request to your URL with this JSON body:

{
  "event_type": "form.completed",
  "timestamp": "2026-04-15T10:30:00Z",
  "data": {
    "id": 123,
    "submission_id": 456,
    "email": "signer@example.com",
    "status": "completed",
    ...
  }
}

The data shape depends on the event type:

• form.* events include submitter details (id, email, name, status, values, documents)
• submission.* events include submission details (id, status, submitters, template)
• template.* events include template details (id, name, fields, submitters)

If a secret header is configured, it is included in every request for your server to verify authenticity.

Events (Polling)

As an alternative to webhooks, you can poll for events.

Form Events

GET /api/events/form/:type

List form-related events (e.g., form.completed).

Submission Events

GET /api/events/submission/:type

List submission-related events (e.g., submission.completed).

Same pagination parameters as form events.

File Upload

Upload Attachment

POST /api/attachments

No authentication required — uses submitter slug for authorization.

Pagination

List endpoints support cursor-based pagination:

{
  "data": [...],
  "pagination": {
    "count": 10,
    "next": 123,
    "prev": 456
  }
}

Use after and before query parameters with the cursor values.

Error Responses

Error format:

{
  "error": "Description of the error"
}

Roles & Permissions

Rate Limits

The API does not enforce hard rate limits by default, but the phone verification endpoint (/api/send_phone_verification_code) has a 60-second cooldown per phone number.