How to Automate PDF Signing with the REST API

Manual PDF signing doesn't scale: open, place signature, enter PIN, save, repeat. If your team signs hundreds of invoices, contracts or certificates a day, that's someone's whole afternoon. Here's how to automate the entire flow with OneSigner in about ten minutes.

Prerequisites

• OneSigner installed and licensed (install guide)
• USB token plugged into the server, certificate visible in Windows
• A signing profile with the certificate, PIN and signature position configured

Level 1: One Call, Signed File Back

curl -X POST "http://localhost:9440/api/upload?download=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@invoice.pdf" -o invoice-signed.pdf

OneSigner matches your token's tenant to a signing profile, finds the signature position (e.g. anchored to the text "Authorized Signature"), signs with the USB token and streams the signed PDF back. Drop the ?download=true to get JSON status instead, with the file stored in the signed folder.

Level 2: Position Decided by the Caller

When your application knows exactly where the signature belongs, pass coordinates per request:

curl -X POST "http://localhost:9440/api/upload?download=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@contract.pdf" \
  -F "fixedPage=2" -F "fixedX=100" -F "fixedY=150" \
  -F "signBoxWidth=200" -F "signBoxHeight=80" \
  -o contract-signed.pdf

Coordinates are PDF points from the bottom-left corner. The profile's certificate and appearance are used; only the position changes. Details: Positional Signing API.

Level 3: Zero Code — Folder Watch

No integration at all: configure a profile's source folder (even a network share), and every PDF dropped there is signed and moved to the destination folder within seconds. Your ERP just writes files; OneSigner does the rest. See Folder Watch.

Batching

for f in invoices/unsigned/*.pdf; do
  curl -sf -X POST http://localhost:9440/api/upload \
    -H "Authorization: Bearer $TOKEN" -F "file=@$f"
done

Uploads are handled concurrently; the token performs its ~4-second cryptographic operation serially, and the pipeline drains itself. In our tests, 12 PDFs complete in under 6 seconds end-to-end.

Monitoring

GET /api/signing/status   # engine health, queue, lastError

Point your monitoring at this endpoint — it catches unplugged tokens and expired sessions before your users notice.

What About Documents Other People Must Sign?

That's not an API problem — that's the built-in eSign portal: drag-and-drop fields, email links, sequential signers, audit trail.

Quick Start Guide →