Fields
Fields are the boxes a signer fills in. Each one belongs to one signer and sits at a position on a page.
How positions work
Positions are fractions of the page, from 0 to 1, measured from the top-left corner. That way the same numbers work for any page size.
x: left edge, as a fraction of page widthy: top edge, as a fraction of page heightw,h: width and height, as fractions of the pagepage: page number, starting at 1
To convert from PDF points, divide by the page size. For a US Letter page (612 × 792 points), a box 72 points from the left and 650 points from the top is x = 72 / 612 ≈ 0.118 and y = 650 / 792 ≈ 0.821.
Add fields
Send one field, or up to 200 as {"fields": [...]}. The whole batch succeeds or nothing is added. The file must be ready first, and fields can only be added to drafts.
curl https://api.readyink.ai/v1/documents/doc_c9x1q8/fields \
-H "Authorization: Bearer $READYINK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"fields": [
{"type": "signature", "recipient_id": "rcp_def456", "page": 2, "x": 0.1, "y": 0.8, "w": 0.28, "h": 0.035},
{"type": "date", "recipient_id": "rcp_def456", "page": 2, "x": 0.6, "y": 0.8, "w": 0.18, "h": 0.03},
{"type": "company", "recipient_id": "rcp_def456", "page": 1, "x": 0.1, "y": 0.3, "w": 0.4, "h": 0.03,
"options": {"placeholder": "Company name", "maxLength": 80}},
{"type": "dropdown", "recipient_id": "rcp_def456", "page": 1, "x": 0.1, "y": 0.36, "w": 0.3, "h": 0.03,
"options": {"choices": ["Monthly", "Annual"]}},
{"type": "short_text", "recipient_id": "rcp_def456", "page": 1, "x": 0.5, "y": 0.36, "w": 0.3, "h": 0.03,
"required": false}
]}'| Property | Notes |
|---|---|
type |
One of the 16 types below. Required. |
recipient_id |
The signer who fills it in. Required. |
page |
Page number, starting at 1. Required. |
x, y, w, h |
Position and size, 0–1. Required. |
required |
Whether the signer must fill it in. Default true. |
options |
Settings for the field type. See below. |
Field types
| Type | What the signer gives | Options |
|---|---|---|
signature |
Signature | {} |
initials |
Initials | {} |
date |
Date signed | {} |
name |
Full name | placeholder, maxLength, prefill |
email |
Email address | placeholder, maxLength, prefill |
phone |
Phone number | placeholder, maxLength, prefill |
company |
Company | placeholder, maxLength, prefill |
job_title |
Job title | placeholder, maxLength, prefill |
address |
Address | placeholder, maxLength, prefill |
website |
Website | placeholder, maxLength, prefill |
short_text |
One line of text | placeholder, maxLength, prefill |
long_text |
Several lines of text | placeholder, maxLength, prefill |
number |
A number | min, max, decimals |
dropdown |
Pick one from a list | choices (required) |
single_choice |
Pick one option | choices (required) |
multiple_choice |
Pick any options | choices (required) |
Options
- Text types (
name,email,phone,company,job_title,address,website,short_text,long_text):placeholder(hint text),maxLength(most characters allowed) andprefill(text from your data, such as a name or address from your CRM, shown to the signer as already filled in; they can't change it). number:min,maxanddecimals.dropdown,single_choice,multiple_choice:choices, a list of strings. Required.signature,initials,date: no options. Send{}or leave it out.
A bad field returns 422 invalid_field, and param points at the problem, like fields.3.x or fields.3. In a batch, nothing is added unless every field is valid. Sending no fields, or more than 200, returns 422 invalid_fields.
Move, change or remove a field
On drafts, PATCH /documents/{id}/fields/{fid} changes any property, including which signer it belongs to. DELETE removes it. Removing a recipient also removes their fields.
If you'd rather not work out coordinates, create the document in the readyink.ai app, where AI suggests the fields for each signer. Then use the API to track it and download the result.