Placing signature fields in PDFs via API
Placing fields through an API means specifying each field's page, position, size, and assigned signer as structured data when you create a signature request, instead of dragging a box onto a page in a visual editor. This matters most when you're sending the same document repeatedly, or generating documents dynamically, since it lets you define field placement once in code rather than positioning it by hand every time.
What a field needs to be positioned correctly
Each field in a request's fields array typically needs:
- Page number — which page of the PDF the field appears on.
- X and Y position — the field's coordinates on that page.
- Width and height — how large the field's box is.
- Field type — signature, initials, date, text, checkbox, radio, or select.
- Assigned signer — which signer on the request is responsible for completing it.
- Required — whether the signer must complete it before the document can be finished.
A minimal example
const fields = [
{
field_type: "signature",
page_number: 3,
x_position: 420,
y_position: 680,
width: 200,
height: 60,
signer_email: "signer@example.com",
required: true,
},
{
field_type: "date",
page_number: 3,
x_position: 420,
y_position: 740,
width: 120,
height: 30,
signer_email: "signer@example.com",
required: true,
},
];
This field array is passed alongside the document and signer list when creating the signature request — see the developer's guide to the API for how it fits into the full request.
Working out coordinates without a visual editor
The hardest part of positioning fields through code, rather than clicking on a page, is figuring out the actual coordinates for a specific document. A few practical approaches:
- Use a known template. If you're sending the same document repeatedly (a standard service agreement, an offer letter), position the fields once using the dashboard's visual editor, note down the resulting coordinates, and reuse them in your API calls for every future document generated from that same template.
- Generate the PDF and the field positions together. If your application is already generating the PDF dynamically (filling in a contract template with customer-specific data, for example), you control exactly where the signature block sits on the page, so you can calculate the field coordinates from the same data used to generate the document layout.
- Leave reasonable margin for variation. If the page content shifts slightly between generated documents (a longer company name, an extra line of text), position fields with enough surrounding space that small content variation doesn't cause a field to overlap text.
Placing fields per signer on a multi-signer document
Each field is tied to a specific signer by their identifier in the request, which means a multi-signer document can have different fields in different positions for each person — a tenant's signature block on one part of the page, a co-signer's on another, each only visible and completable by the signer it's assigned to.
Requiring initials on every page programmatically
For a document where every page needs initials, the straightforward approach through the API is to include one initials field per page, each positioned consistently (the same corner, say) and assigned to the same signer — the platform's repeated-field handling then takes care of letting the signer complete the first one and having the rest fill in automatically, the same way it would if the fields had been placed through the dashboard. See How to require initials on every page for how that propagation behaves from the signer's side.
Field types beyond signature and initials
Beyond signature, initials, and date fields, the same positioning mechanics apply to text fields (for a signer to type in information, like a printed name or an account number) and to selection-style fields like checkboxes, radio buttons, and dropdowns, where applicable to your document.
Testing field placement before sending to a real signer
Before relying on programmatically placed fields in production, create a test request against a document you control and open the resulting signing link yourself to visually confirm the fields land where you expect. Coordinate systems and page dimensions are an easy place to get an off-by-a-few-pixels error that's hard to catch just by reading the numbers in your code.
What happens if a field's coordinates fall outside the page
Fields positioned with coordinates that don't actually correspond to content on the page (off the edge, or on a page number the document doesn't have) won't render usefully for the signer — it's worth validating that your generated coordinates stay within the actual page dimensions, especially if page size or orientation can vary across the documents you're sending.
Validating field data before sending it
Since field placement is structured data rather than something visually confirmed as you place it, it's worth validating the shape of your fields array in your own code before sending it — checking that every field has a valid field_type, that coordinates are numbers within sensible bounds, and that every field references a signer who's actually included in the request. Catching a malformed field on your own side, with a clear error message pointing at which field and what's wrong, is considerably easier to debug than discovering it only after the API rejects the whole request, or worse, accepts it with a field positioned somewhere unusable.
Reusing field layouts across similar documents
If you regularly send structurally similar documents — the same contract template with different customer names and dates filled in, for instance — it's worth keeping the field layout (the array of field objects, independent of which specific document they're attached to) as a reusable piece of configuration in your own codebase, parameterized only by things that actually change between sends, such as which signer email goes with which role. This avoids re-deriving coordinates by hand for every new document generated from the same underlying template.
Field labels and placeholders
Beyond position and type, a field can carry a label and a placeholder that help the signer understand what's expected of them — particularly useful for text fields, where a signer completing a form-like document benefits from knowing whether a given field expects a name, a date, or something else entirely. Leaving these blank still produces a functional field, but a labeled field reduces the chance of a signer misunderstanding what they're meant to fill in.
How this compares to redesigning the document itself
An alternative to carefully calculating field coordinates for an existing PDF layout is to design the document's layout around where the fields will go in the first place — leaving deliberate blank space for a signature block, dated acknowledgment, and so on, rather than trying to fit fields into a layout that wasn't designed with them in mind. If you control how the underlying document is generated (rather than working with a fixed, pre-existing PDF), designing the layout and the field positions together from the start tends to produce a cleaner result than retrofitting fields afterward.
Position fields programmatically
Esignapi's API documentation has the exact field schema and supported field types for positioning signature, initials, date, text, and selection fields through the API.
Frequently asked questions
Do field coordinates use the same units as the visual editor?
Yes — fields placed through the API use the same underlying coordinate system as fields placed through the dashboard's visual editor, so a template positioned visually once can be reused as fixed coordinates in your API calls.
Can I mix API-placed fields with fields added later through the dashboard?
Once a request is created, its fields are fixed for that specific request — if you need to change field placement, that generally means creating a new request rather than editing one already sent.
What happens if I don't specify a page number for a field?
Every field needs an explicit page number tied to the actual document, since there's no reliable default placement that would make sense across documents of different lengths.
Can different field types have different required settings?
Yes, each field's required setting is independent — you could, for example, require a signature while leaving an optional text field for additional comments.
How do I handle a document whose layout changes between sends (variable length, for instance)?
If page count or layout genuinely varies between generated documents, calculate field coordinates dynamically from the same logic that generates the document's content, rather than relying on a single fixed set of coordinates across all versions.