TL;DR: eSignature fields usually land in the wrong spot for four reasons: unit or origin mix-ups, a swapped font, an odd page, or the wrong method. Convert points to pixels, embed your fonts, place fields page by page, and use text tags when you build the document. Our eSignature API supports fixed bounds, text tags and fillable field detection.
A signature field sits perfectly on your test PDF. Then a real customer file arrives, and the field drifts sideways or covers a paragraph. Your API call did not change, but the document did.
Test files tend to come from one tool. Production files come from many tools, and each one builds the page a little differently. This guide covers the four causes and the fix for each.
What is the PDF coordinate system?
The PDF coordinate system is the grid a PDF uses to place everything on a page. It measures in points, where one point is 1/72 of an inch.
Think of it like a city map. Every street address only makes sense once you know which corner of the map is zero and which way the numbers grow.
Field positions work the same way. An x and y value is only correct when the tool that reads it agrees on the unit and the starting corner. Apryse’s guide to PDF coordinates goes deeper into page boxes and rotation.
Is the origin at the top-left or the bottom-left, and which way does the Y axis run?
The PDF format puts the origin at the bottom-left corner, and Y grows as you move up the page. Browsers and many design tools put the origin at the top-left, and Y grows as you move down.
That gap matters when you port placement logic between tools. Convert the units but keep the wrong origin, and a field meant for the top of the page can land near the bottom.
Flip the Y value when your source and target start from different corners:
- Take the page height in the same unit as your Y value.
- Subtract the field’s Y value from that height.
- Subtract the field height as well, so the box keeps its top edge.
Cropped pages add one more step. The visible area can sit offset from the raw grid, so read the page’s crop box before you trust a raw value.
How do you convert PDF points to pixels for BoldSign?
Multiply each point value by 96, then divide by 72. Our help article on how to convert x and y coordinates to pixels shows 50 points becoming about 66.67 pixels.
We measure field bounds in pixels. A point covers more distance than a pixel, so point values copied as they are fall about a quarter short. The field lands closer to the corner than you meant, on both axes.
Our guide to placing form fields sets each field with x, y, width and height. Width and height must be greater than zero, and pageNumber starts at 1. Here is a signature field sent with fixed bounds:
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": "alexgayle@boldsign.dev",
"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..."
]
}'
Why does a font change move text away from your fields?
The viewer swaps in another font when a PDF names a font it does not embed. The new font has different letter widths, so a line can reflow and end in a new place.
A printed label such as “Signature:” can then move on the page. Your field keeps its own coordinates, so it ends up beside empty space instead of the label you measured.
The steady fix is to embed every font when you create the source PDF. Most PDF libraries and word processors have an export option for it.
Can you set the font of a field through the API?
Yes. Font settings for a text box field belong to the field, not to the uploaded file.
Our guide on how to customize the font of form fields uses the font, fontSize, fontHexColor and isBoldFont properties. Here they are on one text box:
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": "alexgayle@boldsign.dev",
"signerType": "Signer",
"locale": "EN",
"formFields": [
{
"id": "TextBox1",
"fieldType": "TextBox",
"font": "TimesNewRoman",
"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..."
]
}'
These settings shape what the signer types into the field. The static text already printed in your PDF still depends on the fonts you embedded.
Why can a formula that works on page one fail by page four?
Each page in a PDF has its own size and its own rotation. A formula built on page one breaks on any later page that differs.
A mostly portrait contract with one landscape exhibit is a common case. Code that reuses page one’s size can push the exhibit’s field off the visible page, or turn it sideways.
Each field in a send request carries its own pageNumber, so its bounds belong to one page. Check every page’s size and rotation before you apply fixed bounds to files that users upload.
Which field placement method fits your documents?
Pick the method that matches how the document is made. The guide to placing form fields lists five ways, and three of them place fields from code.
Sending from a template uses fields already saved in the template. Drag and drop needs a person on the embedded request page. The other three suit automated sending.
| Method | Fits when | Watch for |
|---|---|---|
| Fixed bounds | You control the layout and it stays the same between sends | Pixels per page, not PDF points |
| Text tags | Your own code builds the document | The tag must be in the file before you send it |
| Auto-detect fillable fields | The upload already has fillable fields | Converts text box, checkbox, radio button and signature fields only |
How do text tags avoid coordinate math?
Text tags are short markers inside the document text, such as {{text|1|*|Enter name|field_1}}. Set UseTextTags to true, and we turn each tag into a field at its place on the page.
The field follows the text, so page rotation and page size stop mattering. The tag text stays in the file, so match its color to the background. Our post on how to add document fields with text tags walks through the syntax.
Field detection with artificial intelligence (AI) is a different feature. It suggests fields while you build a template in the web app, as our AI form field detection page explains.
Which BoldSign plan do you need for API field placement, and what does it cost?
You can test every method free in the API sandbox. Live sending through the BoldSign API needs the Enterprise API plan.
The Enterprise API plan starts at $30 a month with 40 envelopes, billed yearly in USD. Each extra envelope costs $0.75. AI form field detection in the web app is on the Business, Premium and Enterprise API plans.
How can you check your field placement today?
Run your own documents through each method before real signers see them. Try rotated pages, mixed page sizes and files from different tools.
- Create a free API sandbox account and send test documents to yourself.
- Book a demo to walk through your document types with our team.
- Read our guide to adding form fields with the BoldSign API.
Frequently asked questions
What unit does BoldSign use for form field bounds?
We measure field bounds in pixels. PDF tools usually give positions in points, where one point is 1/72 of an inch, so convert the values before you send them.
How do I convert PDF points to pixels for BoldSign?
Multiply each point value by 96 and divide by 72. For example, 50 points becomes about 66.67 pixels. Convert x, y, width and height the same way.
Is the PDF origin at the top-left or the bottom-left of the page?
The PDF format puts the origin at the bottom-left, with Y going up. Many screen and design tools put it at the top-left, with Y going down, so flip Y when you move values between the two.
Why does a missing font move text in a PDF?
The viewer swaps in another font when the PDF does not embed the one it names. The new font has different letter widths, so lines can reflow and printed labels can move away from your fields.
Can one PDF have pages of different sizes or rotations?
Yes. Each page in a PDF carries its own size and rotation. A landscape exhibit inside a portrait contract is a common case, so read each page's size before you place fields on it.
Which form fields can BoldSign detect in an uploaded PDF?
With AutoDetectFields set to true, we convert fillable text box, checkbox, radio button and signature fields into BoldSign fields. Other field types stay as they are.
When should I use text tags instead of fixed coordinates?
Use text tags when your own code builds the document. The tag sits in the text, so the field follows it even when pages rotate or change size.
How do I test field placement before I send to real signers?
Create a free API sandbox account and send test documents to yourself. Open each one and check that every field sits where you expect, on rotated and odd-sized pages too.