PDFHQ logo

Documents

DocumentationPDF operations

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.

Server-side API keys Signed storage uploads

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#

SettingTypeBehaviour
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

API example · cURL
# 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.

All 10 SDKs ↓Complete Python walkthrough ↓ Complete Bash/cURL walkthrough ↓ All endpoints → Direct uploads → Error handling →

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
PDFHQ logo

PDF tools and document intelligence. Prepare, understand and work with your documents.

© 2026 PDFHQ. All rights reserved.