Positional Signing API (Per-Request Coordinates)

Signing profiles normally fix the signature position (find-by-text or fixed coordinates). Sometimes the caller knows better — a document-management system that computed the exact spot, or a UI where a user picked the position. For these cases the API accepts per-request position overrides.

Parameters

Both POST /api/signing/sign (JSON) and POST /api/upload (multipart form fields) accept these optional parameters:

Units and origin: PDF points (1 pt = 1/72 inch), origin at the bottom-left corner of the page. An A4 page is 595 × 842 pt.

Behaviour

• When the position parameters are present, OneSigner uses the profile's certificate and appearance but places the signature at exactly the given coordinates. Exactly one signature is applied.
• The override applies to that request only — the shared profile configuration is not modified.
• Omit the parameters and the profile's own placement rules apply unchanged.

Example: Manual Sign With Position Override

curl -X POST https://sign.yourcompany.com/api/signing/sign \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "pdf-main",
    "sourcePath": "C:/contracts/agreement.pdf",
    "fixedPage": 2,
    "fixedX": 100,
    "fixedY": 150,
    "signBoxWidth": 200,
    "signBoxHeight": 80
  }'

Example: Upload With Position Override

curl -X POST "https://sign.yourcompany.com/api/upload?download=true" \
  -H "Authorization: Bearer TENANT_TOKEN" \
  -F "file=@agreement.pdf" \
  -F "fixedPage=1" -F "fixedX=350" -F "fixedY=60" \
  -F "signBoxWidth=180" -F "signBoxHeight=70" \
  -o agreement-signed.pdf

Finding the Right Coordinates

• POST /api/signing/find-text returns the page and X/Y of a text pattern — anchor your box relative to it.
• POST /api/signing/render-page returns a PNG of a page for building your own position-picking UI.
• Or skip the math entirely: the portal's Sign myself page is exactly this API with a drag-and-drop front end.

Notes

• Coordinates are interpreted on the page's PDF coordinate system — pages with rotation or crop boxes are handled correctly.
• If the box extends past the page edge, clip it yourself: valid boxes must fit within the page.