Sign PDF (Visible Marks) API
Place a typed name, date or drawn signature image on a PDF using the metered task lifecycle. This does not verify identities or issue certificate-backed cryptographic signatures.
Endpoint and task semantics#
Operation code: sign
Start this operation with POST /v1/tasks and the tool code shown above. Upload and attach source PDFs (or use task-scoped upload endpoints), then call POST /v1/tasks/{task_id}/process with operation settings.
Add a reviewed visible signature, initials or date to documents with permission from the signer.
Inputs: Exactly one sealed PDF; 1–12 marks; maximum 100 MiB and 500 pages (plan limits may be lower). Documents already containing digital signatures are rejected.
Configuration and extra parameters#
| Setting | Type | Behaviour |
|---|---|---|
| marksrequired | object[] | 1–12 marks; each includes page (1-based), x0, y0, x1, y1 in top-left PDF points and kind: typed, date, or drawn. Typed/date marks include text; drawn marks include base64 PNG bytes (without data URL prefix). Images max 96 KiB, 1600 × 600 pixels. |
Options are validated by the API. Unknown settings and unsupported values return an error instead of being ignored.
Working request sequence#
Programming language: cURL
Choose a language · scroll horizontally for all 10 SDK languages
# Server-side API calls. Save the returned task_id.
curl -fsS -X POST 'https://api.pdfhq.io/v1/tasks' \
-H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
-d '{"tool":"sign"}'
# Upload and verify 1 PDF(s), then obtain and approve a credit quote:
curl -fsS 'https://api.pdfhq.io/v1/tasks/TASK_ID/quote' -H 'x-api-key: YOUR_API_KEY'
# ONLY after explicit customer approval:
test "$PDFHQ_APPROVE_QUOTE" = yes || { echo "Approval required" >&2; exit 1; }
curl -fsS -X POST 'https://api.pdfhq.io/v1/tasks/TASK_ID/process' \
-H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
-d '{"options":{"marks":[{"kind":"typed","page":1,"x0":72,"y0":650,"x1":320,"y1":715,"text":"Jane Doe"}]}}'
curl -fsS 'https://api.pdfhq.io/v1/tasks/TASK_ID' -H 'x-api-key: YOUR_API_KEY'After starting a task, upload and verify PDFs, review the credit quote, and get explicit approval before processing. API keys belong on your server, never on signed storage uploads.
Generated downloadable packages cover the task workflow only. Full-service SDKs require a verified runtime OpenAPI specification; the Python, JavaScript and TypeScript task SDKs stream file uploads; the other languages require signed multipart uploads implemented by the caller.
The returned task ID is used for both status polling and retrieval. After the task succeeds, request a signed output URL rather than embedding a download secret.
Output and important details#
New PDF containing visible signature marks in the requested rectangles. Source pages and original text remain accessible.
This operation does NOT create a digital certificate, recipient audit trail, legal-compliance attestation or signer identity verification. Existing PDF digital signatures are rejected; rotated target pages are not supported. For business-grade recipient signature workflows, integrate a dedicated provider.
Errors, retries and billing