SmartDocs API

Quickstart

This guide takes you from zero to your first completed signing request: create an API key, upload a PDF, and send it out for signature. Budget about ten minutes.

All endpoints live under https://api.smartdocs.de/api/v1 and return JSON. Every successful response is wrapped in the same envelope — { "success": true, "data": …, "timestamp": … } — see Conventions for the details.

1. Get an API key

API keys are created in the SmartDocs dashboard — there is no API endpoint for minting keys. Open your organization's settings, go to API keys, and create one:

  • The full key (sdk_live_…) is shown exactly once at creation. Copy it immediately and store it in a secret manager — SmartDocs keeps only a hash.
  • Each key is scoped to one organization and carries a role: ADMIN or MEMBER. This guide uploads PDFs and creates signing processes, which require an ADMIN key.
  • You can optionally set an expiry date when creating the key.

Read Authentication for scoping, rotation, and security guidance.

2. Make your first request

Send the key in the X-API-Key header (an Authorization: Bearer header works too):

curl https://api.smartdocs.de/api/v1/templates \
  -H "X-API-Key: $SMARTDOCS_API_KEY"

A fresh organization has no templates yet, so you get an empty page back — inside the standard success envelope:

{
    "success": true,
    "data": {
        "items": [],
        "total": 0,
        "page": 1,
        "pageSize": 20
    },
    "timestamp": "2026-06-11T09:30:12.481Z"
}

If you see this, your key works. A 401 means the key is missing, invalid, expired, or revoked.

3. Upload a PDF

Uploads are a two-step, direct-to-storage flow: the API hands you a presigned URL, you PUT the bytes straight to storage, then commit. File bytes never flow through the API itself.

Step 1 — initiate. Declare the file name and exact byte size (contentType is optional and must be application/pdf when present):

curl -X POST https://api.smartdocs.de/api/v1/pdf-assets/uploads \
  -H "X-API-Key: $SMARTDOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "consulting-agreement.pdf",
    "sizeBytes": 184302,
    "contentType": "application/pdf"
  }'

{
    "success": true,
    "data": {
        "uploadId": "0d4f0a4e-6c1d-4b54-9d56-1f2f4f9b8a31",
        "uploadUrl": "https://storage.example.com/organizations/…/pdf-assets/…?X-Amz-Signature=…",
        "key": "organizations/1f9e2b7c-…/pdf-assets/0d4f0a4e-….pdf",
        "contentType": "application/pdf",
        "expiresAt": "2026-06-11T09:45:12.481Z"
    },
    "timestamp": "2026-06-11T09:30:12.481Z"
}

Step 2 — PUT the bytes. Upload to uploadUrl before expiresAt (the URL is valid for 15 minutes). The presigned URL is bound to the declared content type and byte count, so send exactly what you declared:

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @consulting-agreement.pdf

Step 3 — commit. Finalize the upload. The API verifies the stored object's size, parses the PDF, and creates the asset:

curl -X POST https://api.smartdocs.de/api/v1/pdf-assets/uploads/0d4f0a4e-6c1d-4b54-9d56-1f2f4f9b8a31/commit \
  -H "X-API-Key: $SMARTDOCS_API_KEY"

{
    "success": true,
    "data": {
        "id": "9b2f8c34-5e1a-4f0b-8c5d-2a7e9d1c6b43",
        "originalFileName": "consulting-agreement.pdf",
        "mimeType": "application/pdf",
        "sizeBytes": 184302,
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
        "pageCount": 4,
        "createdAt": "2026-06-11T09:31:02.110Z",
        "processing": {
            "status": "QUEUED",
            "jobId": "1042",
            "startedAt": null,
            "finishedAt": null,
            "errorMessage": null
        }
    },
    "timestamp": "2026-06-11T09:31:02.143Z"
}

Assets are deduplicated by content: committing a byte-identical PDF returns the existing asset instead of creating a duplicate.

4. Wait for processing

Preview and thumbnail artifacts are generated asynchronously. Poll the processing endpoint until status is READY — the status moves QUEUED → PROCESSING → READY (or FAILED):

curl https://api.smartdocs.de/api/v1/pdf-assets/9b2f8c34-5e1a-4f0b-8c5d-2a7e9d1c6b43/processing \
  -H "X-API-Key: $SMARTDOCS_API_KEY"

{
    "success": true,
    "data": {
        "status": "READY",
        "jobId": "1042",
        "startedAt": "2026-06-11T09:31:03.502Z",
        "finishedAt": "2026-06-11T09:31:06.778Z",
        "errorMessage": null
    },
    "timestamp": "2026-06-11T09:31:08.012Z"
}

Starting a signing process from an asset that is not READY yet fails with a 409. If processing ends in FAILED, errorMessage explains why and you can re-queue it via POST /pdf-assets/{id}/processing/retry.

5. Start a signing process

Create a signing process directly from the asset. This example emails one external signer a hosted signing link, authorized by the link alone (SES_LINK_ONLY):

curl -X POST https://api.smartdocs.de/api/v1/signing-processes \
  -H "X-API-Key: $SMARTDOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dispatchMode": "EMAIL",
    "sourcePdfAssetId": "9b2f8c34-5e1a-4f0b-8c5d-2a7e9d1c6b43",
    "subject": "Consulting agreement — please sign",
    "message": "Hi Erika, please review and sign the agreement.",
    "expiresAt": "2026-06-25T23:59:59.000Z",
    "authPolicy": "SES_LINK_ONLY",
    "signers": [
      {
        "signOrder": 1,
        "name": "Erika Mustermann",
        "email": "erika@example.com",
        "roleLabel": "Client",
        "locale": "de"
      }
    ],
    "fields": [
      {
        "assignedSignerSignOrder": 1,
        "type": "SIGNATURE",
        "label": "Client signature",
        "page": 3,
        "x": 72,
        "y": 640,
        "w": 180,
        "h": 48,
        "required": true
      }
    ]
  }'

A few rules worth knowing:

  • dispatchMode is one of EMAIL, KIOSK, or CURRENT_USER. With EMAIL, every external signer must include an email — SmartDocs delivers the hosted signing link for you; your integration never builds or sends signing URLs itself.
  • authPolicy is AES_OTP (the default when omitted) or SES_LINK_ONLY. AES_OTP requires each external signer to pass an SMS one-time code, so those signers must include phoneE164 — and SMS signing requires a paid plan.
  • signOrder values must be unique and sequential starting at 1; signers sign in that order.
  • Field type is one of TEXT, DATE, CHECKBOX, or SIGNATURE. page is the zero-based page index; x, y, w, h position the field on the page in PDF points.
  • Every field's assignedSignerSignOrder must reference one of the declared signers.

The process is created and sent in one step — there is no draft state. The response contains the new process with its signer slots and field definitions (truncated here to the most useful fields; the full payload also embeds the source asset metadata):

{
    "success": true,
    "data": {
        "id": "31f0d4c9-8a2e-47f5-b1c3-6e9d0a5b7f21",
        "status": "SENT",
        "origin": "DIRECT",
        "dispatchMode": "EMAIL",
        "authPolicy": "SES_LINK_ONLY",
        "subject": "Consulting agreement — please sign",
        "expiresAt": "2026-06-25T23:59:59.000Z",
        "sentAt": "2026-06-11T09:32:10.512Z",
        "signerSlots": [
            {
                "id": "7d5a1b8e-3c4f-49a2-9e6b-0f8c2d1a5e74",
                "signOrder": 1,
                "roleLabel": "Client",
                "name": "Erika Mustermann",
                "email": "erika@example.com",
                "status": "READY"
            }
        ]
    },
    "timestamp": "2026-06-11T09:32:10.540Z"
}

Erika receives an email with her personal signing link. Track progress any time:

curl https://api.smartdocs.de/api/v1/signing-processes/31f0d4c9-8a2e-47f5-b1c3-6e9d0a5b7f21 \
  -H "X-API-Key: $SMARTDOCS_API_KEY"

The process status moves SENT → IN_PROGRESS → COMPLETED (or DECLINED, VOIDED, EXPIRED). Once completed, the process carries the final signed PDF and a completion certificate.

Next steps

  • Authentication — key scoping, rotation, and security best practices.
  • Core Concepts — templates, signing processes, signers, and the audit trail.
  • Conventions — envelopes, error codes, rate limits, and pagination.
  • API Reference — every endpoint, parameter, and schema.