PDFHQ logo

Documents

eSignature requests API

Create and edit versioned signature drafts, place and validate sender-assigned fields, dispatch explicit sandbox requests and retrieve signed artifacts.

Server-side API keys Signed storage uploads

Signature request lifecycle — sandbox first#

PDFHQ eSign supports a provider-neutral envelope resource: upload and verify one PDF with POST /v1/documents/uploads, then create a signature-request draft. Drafts have their own identity, signers and status separate from PDF conversion tasks.

Current release: Dropbox Sign test mode only. Test documents are watermarked and not legally binding. The provider sends its own signer emails. Live signature requests, enterprise OAuth connections and production tariffs are not enabled.

Create an eSignature draft
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"upload_id":"VERIFIED_UPLOAD_UUID","provider":"managed","title":"Mutual NDA","subject":"Please review and sign","message":"Please sign this agreement.","signers":[{"name":"Alice Example","email":"alice@example.com","order":0},{"name":"Bob Example","email":"bob@example.com","order":1}]}'

Prepare exact signer fields and versioned drafts#

Sandbox clients can place signature, initials and signing-date fields on a sealed, upright, uncropped US Letter PDF. Public rectangle coordinates are normalized from 0 to 1 relative to the top-left corner of the page; the page number starts at 1. Each signer must receive a required signature field. Reject overlapping, missing or out-of-bounds placements. For all other page sizes, omit fields to use the provider's appended signature page while support is being validated.

Create positioned, two-signer draft
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Idempotency-Key: sample-signing-draft-001' \
  -H 'Content-Type: application/json' \
  -d '{"upload_id":"VERIFIED_UPLOAD_UUID","provider":"managed","title":"NDA", "subject":"Sign NDA","message":"Please review and sign","signers":[{"name":"Example One","email":"first@example.test","order":0},{"name":"Example Two","email":"second@example.test","order":1}],"fields":[{"field_id":"first_sig","signer_index":0,"type":"signature","page":1,"rect":{"x":0.10,"y":0.72,"width":0.30,"height":0.08},"required":true},{"field_id":"second_sig","signer_index":1,"type":"signature","page":1,"rect":{"x":0.55,"y":0.72,"width":0.30,"height":0.08},"required":true}]}'

Creation is idempotent with an optional Idempotency-Key. The same key and same sealed document/draft data return the existing draft; a different payload returns 409. A draft can be edited only before dispatch by PATCH /v1/esign/envelopes/ENVELOPE_UUID with a complete replacement field set and If-Match: 1 from its draft_version. Edits increment the version and digest. Fields remain immutable after dispatch.

Preflight exact source and field layout
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/validate' \
  -H 'x-api-key: YOUR_API_KEY'

This preflight compares page dimensions and rotation against actual sealed bytes, not browser metadata. It is rate limited and read-only. A passing local preview does not certify Dropbox Sign pixel-perfect placement; review the actual test signing ceremony before production activation.

Dispatch with explicit test acknowledgement#

cURL
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/send' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"confirm_test_mode":true,"draft_version":1}'

# Poll the envelope for status; never auto-retry an uncertain send.
curl 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID' -H 'x-api-key: YOUR_API_KEY'

Provider dispatch is guarded by an explicit server-side configuration and disabled in production. Requests that may have reached Dropbox but lost their response enter needs_reconciliation and cannot be resent blindly.

Sandbox reminders and cancellation — signed callbacks are authoritative#

After a test request is sent, the sender may issue one test email reminder per recipient in 24 hours. Cancel requests use the provider API asynchronously; an HTTP 202 only means cancellation was requested, not that recipients can no longer sign. Neither operation is a production electronic-signature workflow.

Request one recipient reminder
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/remind'   -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"recipient_index":0,"confirm_test_mode":true}'

curl 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/reminders'   -H 'x-api-key: YOUR_API_KEY'

Reminder receipts report acceptance/rejection/uncertainty, not actual email delivery. An attempted reminder is durably recorded before contacting the provider; if the network result is uncertain, do not retry. Only callers within the original account/API project can access receipts; signer emails are excluded.

Request async cancellation; inspect status
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/void'   -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"reason":"agreement_withdrawn","confirm_test_mode":true}'

curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/sync'   -H 'x-api-key: YOUR_API_KEY'

Cancellation is permitted only while sent, viewed or awaiting delivery. Partially signed and completed requests cannot be cancelled from PDFHQ. Provider HTTP 200 does not mean the envelope has been voided. Wait for an authenticated signature_request_canceled callback or confirmed provider status. Responses such as cancel_uncertain require operator investigation; never blindly submit again.

This API does not promise deletion of previously emailed invitations, legal enforceability, retroactive cancellation of an existing signature, automatic refunds or production-grade provider SLA. Future live mode requires central credit-based billing, identity verification, contractual review and complete staging provider acceptance.

Signed document retrieval#

After a verified signature_request_downloadable callback, use POST /v1/esign/envelopes/ENVELOPE_UUID/archive . PDFHQ downloads the completed PDF from Dropbox into the private HQ storage namespace. Then retrieve GET /v1/esign/envelopes/ENVELOPE_UUID/download-url for a short-lived, account-scoped output URL.

The source PDF is never sent through a customer-specified URL. We forward verified sealed file bytes to the fixed Dropbox API host. Provider-hosted signer pages and provider audit evidence are managed by the selected service.

Webhook security and state transitions →
PDFHQ logo

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

© 2026 PDFHQ. All rights reserved.