API reference

Fields

Where each signer signs, initials, dates or fills in. Positions are fractions of the page.

Endpoints · 4

POST Add fields
GET List fields
PATCH Update a field
DELETE Delete a field

The object

Field	Type	Description
`id`	string	Unique ID, starting with fld_.
`object`	string	Always "field".
`recipient_id`	string	The signer who fills it.
`file_id`	string	The file it is on.
`type`	enum	signature, initials, date_signed, name, text, checkbox or attachment (the signer uploads a file).
`page`	integer	Page number in that file, from 1.
`x, y`	number	Top-left corner, as a fraction of the page width and height (0 to 1), from the top-left of the page.
`width, height`	number	Size as a fraction of the page (0.005 to 1).
`required`	boolean	Whether the signer must fill it. Checkboxes are never required.
`label`	string or null	Shown to the signer, up to 80 characters.

POST/documents/{id}/fields

Add fields

Drafts only. Returns all the document’s fields.

Parameter	Type		Description
`fields`	array	required	1 to 500 fields. Each has recipient (a recipient ID, or email), type, page, x, y, width, height, and optionally file (a file ID; default the first file), required and label.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/fields" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fields": [ { "recipient": "rcp_5ZR3qa7yEeeby3abP3E2Zs", "type": "signature", "page": 6, "x": 0.12, "y": 0.71, "width": 0.3, "height": 0.06 } ] }'

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "fld_2a3dDVhYRnKTbxTNJFoBin",
      "object": "field",
      "recipient_id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "file_id": "file_5aJXVuLkSIc47WQAmL9xVQ",
      "type": "signature",
      "page": 6,
      "x": 0.12,
      "y": 0.71,
      "width": 0.3,
      "height": 0.06,
      "required": true,
      "label": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/documents/{id}/fields

List fields

By page, top to bottom.

Request

bash

curl "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/fields" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "fld_2a3dDVhYRnKTbxTNJFoBin",
      "object": "field",
      "recipient_id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "file_id": "file_5aJXVuLkSIc47WQAmL9xVQ",
      "type": "signature",
      "page": 6,
      "x": 0.12,
      "y": 0.71,
      "width": 0.3,
      "height": 0.06,
      "required": true,
      "label": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

PATCH/documents/{id}/fields/{field_id}

Update a field

Drafts only.

Parameter	Type		Description
`page, x, y, width, height, required, label`		optional	As in Add fields.

Request

bash

curl -X PATCH "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/fields/fld_2a3dDVhYRnKTbxTNJFoBin" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "y": 0.74 }'

Response

json

{
  "id": "fld_2a3dDVhYRnKTbxTNJFoBin",
  "object": "field",
  "recipient_id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
  "file_id": "file_5aJXVuLkSIc47WQAmL9xVQ",
  "type": "signature",
  "page": 6,
  "x": 0.12,
  "y": 0.71,
  "width": 0.3,
  "height": 0.06,
  "required": true,
  "label": null
}

DELETE/documents/{id}/fields/{field_id}

Delete a field

Drafts only.

Request

bash

curl -X DELETE "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/fields/fld_2a3dDVhYRnKTbxTNJFoBin" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{ "id": "fld_2a3dDVhYRnKTbxTNJFoBin", "object": "field", "deleted": true }