You can create and edit Fields with an API endpoint

A Field created with an API endpoint is a Field that is explicitly positioned on a Document via the API, by specifying the page number and precise coordinates (X/Y).

Unlike Smart Anchors, which rely on text-based placeholders included in the Document, Manual Fields require an exact placement definition once the Document is uploaded on Yousign.

Each Manual Field must be associated with either a Signer or a Document.

Two ways to create Fields via API are available

Using the dedicated Field endpoint (recommended) POST /signature_requests/{signatureRequestId}/documents/{documentId}/fields and attach a Field to a specific Document after the Signer is created.
When creating a Signer: pass a Fields array directly in the POST /signature_requests/{signatureRequestId}/signers request body.

Both approaches are supported. However, we recommend using the dedicated Field endpoint, especially if you need advanced configuration or plan to update Fields independently later. Details of available features for each option are documented in the API reference.

How to create Fields with API endpoints?

Step-by-step guide

Create a Signature Request, upload a Document and add a Signer.
Add Fields to your Signature Request using this endpoint: /POST signature_requests/{signatureRequestId}/documents/{documentId}/field

Mandatory parameters

For each manual field, you should at least set the following parameters:

Attribute	Description
`signer_id`	Id of the Signer on which the Field will be attached
`document_id`	Id of the Document on which the Field will be added
`type`	The type of Field.
`page`	The page of the Document on which the Field is positioned
`x`	The top-left x coordinates of the Field with the x-axis starting at the left of the page
`y`	The top-left y coordinates of the Field with the y-axis starting at the top of the page

Coordinates

All coordinates are based on the top left of the page.

We will take an example of a PDF document in A4 format (width: 596px, height: 842px).

On this page:

The top left coordinate of the page is x0, y0.
The Signer 1’s Signature Field coordinate is x1, y1.
The Signer 2’s Signature Field coordinate is x2, y2.

💡
If you're unsure about field placement, try PlaceIt a tool designed to help with coordinate management: upload your document, position your field, and instantly retrieve the correct coordinates.

Why create Fields with API endpoints?

Fields created with API endpoints are particularly useful when:

You need a very precise placement for each Field.
You need to customise the Field appearance.
Your document generation tool or format does not support Smart Anchors.
You are dynamically generating documents and defining Field positions programmatically.
You want to add Fields at different times—either when creating a Signer or updating an existing Signature Request.