API documentation

Overview

Base URL

https://snapfritz.com/api/v1

Format

JSON (UTF-8); uploads as multipart/form-data or application/pdf

Plan

Platin – without it calls answer 403 plan_required

Version

v1 – additions are backwards compatible

The flow is always the same:

1. Upload – fields are extracted right away
2. Review and confirm the fields (or hand over to a human)
3. Sign
4. Download the finished PDF

Authentication

Every request carries an API key in the Authorization header. Create keys under Developer; they are shown once and stored only as a hash. A key belongs to exactly one account and may only do what its scopes allow.

Authorization: Bearer sf_live_…

Treat the key like a password: never commit it to a repository or ship it in a client app. If in doubt, revoke it under Developer and create a new one.

Quickstart

A complete run. Replace $DOC and $FIELD with the ids from the responses.

export SNAPFRITZ_API_KEY=sf_live_…

# 1. upload
curl -s -X POST https://snapfritz.com/api/v1/documents \
  -H "Authorization: Bearer $SNAPFRITZ_API_KEY" \
  -F file=@formular.pdf

# 2. confirm a field (omit "value" to accept the suggestion)
curl -s -X POST https://snapfritz.com/api/v1/documents/$DOC/fields/$FIELD/confirm \
  -H "Authorization: Bearer $SNAPFRITZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "Erika Muster"}'

# 3. sign (needs the documents:sign scope)
curl -s -X POST https://snapfritz.com/api/v1/documents/$DOC/sign \
  -H "Authorization: Bearer $SNAPFRITZ_API_KEY"

# 4. download the filled PDF
curl -s https://snapfritz.com/api/v1/documents/$DOC/download \
  -H "Authorization: Bearer $SNAPFRITZ_API_KEY" -o ausgefuellt.pdf

The same as a Python script

Confirms confidently recognised fields automatically and hands everything uncertain to a human.

import os
import requests

BASE = "https://snapfritz.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['SNAPFRITZ_API_KEY']}"}

with open("formular.pdf", "rb") as f:
    doc = requests.post(f"{BASE}/documents", headers=H, files={"file": f}, timeout=120)
doc.raise_for_status()
doc = doc.json()
if doc["status"] == "failed":
    raise SystemExit("PDF not readable")

for field in doc["fields"]:
    if field["confirmed"] or field["state"] in ("not_applicable", "out_of_scope"):
        continue
    if field["state"] != "ok":
        # unsure / missing / hand: decide yourself or hand over to a human
        raise SystemExit(f"Needs a decision: {field['label']} -> {doc['reviewUrl']}")
    requests.post(f"{BASE}/documents/{doc['id']}/fields/{field['id']}/confirm",
                  headers=H, json={}).raise_for_status()

requests.post(f"{BASE}/documents/{doc['id']}/sign", headers=H).raise_for_status()
pdf = requests.get(f"{BASE}/documents/{doc['id']}/download", headers=H)
open("ausgefuellt.pdf", "wb").write(pdf.content)

Example upload response

Shortened to one field; values are examples.

{
  "id": "3f0c2d5e-8a4b-4f0e-9c1a-2b7d6e5f4a31",
  "filename": "formular.pdf",
  "title": "Anmeldung",
  "documentType": "registration",
  "status": "ready_for_review",
  "pageCount": 2,
  "requiresStrongerSignature": false,
  "requiresStrongerSignatureReason": null,
  "createdAt": "2026-09-25T13:04:11.000Z",
  "signedAt": null,
  "sentAt": null,
  "downloadable": false,
  "reviewUrl": "https://snapfritz.com/documents/3f0c2d5e-8a4b-4f0e-9c1a-2b7d6e5f4a31",
  "fields": [
    {
      "id": "b1f7c8a0-52de-4c1e-8f3a-9d0e7a6b5c42",
      "page": 1,
      "type": "text",
      "label": "Nachname",
      "semanticKey": "last_name",
      "state": "ok",
      "value": "Muster",
      "source": "profile",
      "confirmed": false,
      "checkboxGroup": null
    }
  ]
}

Endpoints

All paths are relative to the base URL. Ids are UUIDs; foreign or malformed ids answer 404.

Machine-readable description for client generators and agent frameworks: OpenAPI 3.1 (JSON)

Objects

The public shape of a document and its fields. Internal details such as storage locations are deliberately not part of it.

Field state (state)

Document status (status)

Errors

Errors always have this shape; the code is stable and meant for programs, the message for humans:

{ "error": { "code": "not_found", "message": "Document not found." } }

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": {
    "code": "quota_exceeded",
    "message": "The plan's upload allowance for this period is used up.",
    "quota": { "kind": "uploads", "plan": "platin", "used": 200, "limit": 200, "resetsAt": "2026-10-25T00:00:00.000Z" }
  }
}

Limits & allowance

• 60 requests per minute per key, of which at most 10 uploads. Beyond that: 429 with Retry-After (seconds); every response carries X-RateLimit headers.
• PDFs up to 20 MB and 20 pages. The plan counts finished forms (every successful sign) and, twice as many, readable uploaded PDFs.
• When either is used up, upload or sign answer 402 quota_exceeded. Nothing is billed on top. GET /usage tells you beforehand how much is left and when it renews.
• Extraction runs synchronously inside the upload request and can take up to about a minute – set your client timeout accordingly (≥ 120 s).
• Everything done with a key appears in the account's log as “API key <prefix>”.

For agents

• Check state and confirmed of each field. Auto-confirm only ok; for unsure, missing and hand decide yourself or hand over to a human via reviewUrl.
• Call GET /usage before uploading to avoid 402.
• On 429 wait for Retry-After, on 5xx retry with backoff. POST …/sign is idempotent; uploads are not – after a timeout check GET /documents first instead of blindly re-uploading.
• Grant documents:sign only to keys that really should sign, and keep read and write keys apart.
• Documents with requiresStrongerSignature = true can't be signed via the API – they belong in the review screen.