How the PDF Coordinate System Affects eSignature Fields

TL;DR: eSignature form fields usually land in the wrong spot for one of four reasons: a coordinate system mismatch, a substituted font that shifted the text you're anchoring to, a rotated or differently sized page that broke a formula built for page one, or a placement method that doesn't match how the document was actually built.

Knowing these four failure modes, and matching your placement method to your document type, prevents most of them before you have to debug a signer’s screenshot.

A signature field that sits perfectly in your test PDF shows up noticeably offset, sideways, or overlapping a paragraph the moment a real customer document hits your integration. The API call didn’t change. The document did, and now you’re looking at a resend or a signer who can’t find where to sign.

This is one of the most common failure modes in eSignature API integrations, and one of the most avoidable. Developers place fields using coordinates or content markers that work fine against a handful of test files, then hit trouble once production PDFs, generated by different tools, don’t share that same internal structure.

Four specific patterns cause most of it: getting the coordinate math backwards, losing a font partway through rendering, a page that’s rotated or a different size than the ones around it, and reaching for the wrong placement method for the document. They’re common enough that you’ve probably already hit at least one without realizing what caused it.

Here’s why each happens, and the specific fix for each: measuring in the right units, embedding a font instead of relying on the viewer, scoping coordinates per page, or picking a different placement method entirely.

Key takeaways

• Most field-placement bugs trace back to a wrong assumption about a document’s internal structure, not a mistake in the API call itself.
• BoldSign’s field bounds are measured in pixels from the page’s top-left corner, not PDF’s native point-based, bottom-left system, so coordinates copied from a PDF-native tool need both the unit and the origin converted.
• A font that isn’t embedded in the source document gets substituted by the viewer, which can shift a printed label enough to misalign any field placed at fixed coordinates next to it.
• Page rotation and page-by-page size differences mean a coordinate formula that works on page one of a document can fail by page four.
• Matching your placement method (fixed coordinates, content-anchored tags, or automatic detection) to how the document was actually produced prevents most of these failures before they start.

PDF’s coordinate system and BoldSign’s aren’t the same one

Most developers picture coordinates the way a browser or a design tool does: origin in the top-left corner, Y increasing as you move down the page. PDF’s own specification doesn’t work that way. It places the origin at the bottom-left corner, with Y increasing upward, measured in points (1/72 of an inch), the same way you’d plot points on a math graph.

It gets messier with cropped pages, since a page’s visible area can sit offset from its raw coordinate space. For a deeper technical walkthrough of these coordinate spaces outside the eSignature context, Apryse’s explainer on PDF coordinate systems covers the same origin and rotation mechanics in more depth.

BoldSign doesn’t ask you to work in that system directly. Its bounds property is measured in pixels, from the page’s top-left corner, the same convention most screens, browsers, and design tools already use. That’s a deliberate simplification, not an oversight.

The place this actually bites: if you’re measuring in points, from a PDF library, a design tool, or documentation quoting PDF-native coordinates, and pass those numbers straight into BoldSign’s bounds, the field lands closer to the corner than intended in both directions, about a quarter short, since a point covers more physical distance than a pixel does. Converting points to pixels takes a 96/72 multiplier, not a straight copy.

The other place it bites: if you’re porting placement logic from a tool that uses PDF-native coordinates (bottom-left origin, Y-up), converting the units without accounting for the different coordinate origin can place a field meant for the top of the page near the bottom instead.

BoldSign’s fixed-bounds placement takes x, y, width, and height per field, in pixels, from the page’s top-left corner, not the PDF’s own point-based, bottom-left system:

curl -X POST "https://api.boldsign.com/v1/document/send" \ 
  -H "accept: application/json" \ 
  -H "X-API-KEY: YOUR_API_KEY" \ 
  -H "Content-Type: application/json" \ 
  -d '{ 
    "Title": "Sample Document", 
    "Signers": [ 
      { 
        "name": "Alex", 
        "emailAddress": "[email protected]", 
        "signerType": "Signer", 
        "locale": "EN", 
        "formFields": [ 
          { 
            "fieldType": "Signature", 
            "pageNumber": 1,
             "bounds": { 
              "x": 50, 
              "y": 50, 
              "width": 125, 
              "height": 25 
            }, 
            "isRequired": true 
          } 
        ] 
      } 
    ], 
    "Files": [ 
      "data:application/pdf;base64,JVBERi0xLjcKJcfs..." 
    ]
  }'

For documents whose layout isn’t stable enough to hardcode, text tags skip coordinate math entirely. You drop text tag syntax inside the document itself, and BoldSign converts that syntax into equivalent form fields at the tag’s location, so there’s no need to manually calculate field bounds.

The font in your source document might not be the font that renders

If a PDF references a font that isn’t embedded in the file, the viewer has to substitute something else at render time. That’s not just cosmetic. Different fonts have different letter widths, so a substitution can reflow a line, push text further than expected, or shift where a line actually ends.

That matters most when you’re using fixed coordinates next to a printed label, like “Signature:”. A substituted font can shift that label’s position on the page even though the field’s own coordinates never changed, so the field ends up sitting next to whitespace instead of the text it was measured against.

For text box fields, the font family, size, and color are properties of the field itself, not the document you uploaded. You can set them explicitly through the API rather than depending on whatever font the uploaded document happens to reference:

curl -X POST "https://api.boldsign.com/v1/document/send" \ 
  -H "accept: application/json" \ 
  -H "X-API-KEY: YOUR_API_KEY" \ 
  -H "Content-Type: application/json" \ 
  -d '{ 
    "Title": "Sample Document", 
    "Signers": [ 
      { 
        "name": "Alex", 
        "emailAddress": "[email protected]", 
        "signerType": "Signer", 
        "locale": "EN", 
        "formFields": [ 
          { 
            "id": "TextBox1", 
            "fieldType": "TextBox", 
            "font": "TimesRoman", 
            "fontSize": 16, 
            "fontHexColor": "#035efc", 
            "isBoldFont": true, 
            "pageNumber": 1, 
            "bounds": { 
              "x": 200, 
              "y": 200, 
              "width": 125, 
              "height": 25 
            }, 
            "isRequired": true 
          } 
        ] 
      } 
    ], 
    "Files": [ 
      "data:application/pdf;base64,JVBERi0xLjcKJcfs..." 
    ] 
  }'

That controls the field’s own content, not the static text already baked into the document you uploaded. The more reliable fix is to embed fonts in the source PDF when generating it, so nothing needs to be substituted at render time.

Why a formula that works on page one can fail by page four

A PDF isn’t one flat coordinate space. It’s a series of pages, and each page can carry its own rotation and its own dimensions independent of the others. A mostly portrait contract with one rotated landscape exhibit in the middle is common enough to eventually show up in production, even if none of your test files had one.

If your placement logic assumes every page shares page one’s orientation and size (an easy shortcut when you’re iterating fast), a field meant for page four can inherit page one’s dimensions instead. It ends up outside the visible page, or mirrored, depending on how that page was rotated.

BoldSign limits the blast radius here because fixed-bounds placement is specified per field with its own pageNumber, tying each field’s coordinates to a single page rather than one global transform your code has to maintain. Text tags sidestep this specific problem, since a tag’s position comes from where it actually appears in the document, not from a coordinate calculation that a page’s rotation or size could throw off.

That reduces how much rotation math your own code needs to carry, but it doesn’t remove the need to know your document’s structure. If you’re accepting user-uploaded contracts and placing fields by fixed coordinates, check page count and orientation before assuming one layout applies to every page.

Choosing a placement method before you need to debug one

BoldSign documents five ways to place fields on a document overall: sending from a template, exact bounds, text tags, auto-detecting existing fillable fields, and dragging fields into an embedded request.

The table below covers the three that are genuinely callable from the API. Template-based sending is a different workflow, and drag-and-drop needs a human in the web app UI, so neither one is really a way to place fields programmatically.

One more thing worth flagging: AI-based field detection is a separate BoldSign feature available in the template creation workflow of the web application. It’s different from auto-detecting existing fillable fields, which works with fields already present in the uploaded PDF.

Match your method to your documents before you build

None of this is exotic. All four failure modes from the start of this article (the coordinate mismatch, the font substitution, the per-page rotation, and the wrong placement method for the job) come from the same root cause: a document’s internal structure rarely matches the clean assumptions your first test file supported. Matching a placement method to how your documents are actually produced, before you build, is cheaper than debugging coordinates after signers start complaining.

If you’re setting up field placement for the first time, BoldSign’s developer documentation covers the available field-placement options, including template-based sending and embedded drag-and-drop. Create a free API sandbox to test them against your own documents.

FAQs