Places
Place Object
Define signature fields, input areas, and auto-filled values at specific locations in documents
A place is a location on a document where a recipient performs an action or where information is displayed automatically. Places define where signatures go, where recipients type text, and where dates or names are inserted.
Places are defined in the places array on a document. Each element in the array represents one place within the document. The properties available on a place depend on its type.
A place belongs to a document.
Place Types
There are three categories of place: signature places for capturing signatures and initials, interactive places that require other input from a recipient, and informational places that insert values automatically.
Signature places
| Type | Description |
|---|---|
signature | The recipient draws or types their signature |
initials | The recipient enters their initials |
Interactive places
Interactive places require sequential routing.
| Type | Description |
|---|---|
text_input | The recipient types free-form text |
boxed_text_input | The recipient enters text into individual character boxes |
multiline_text_input | The recipient types text across multiple lines |
dropdown | The recipient selects from a list of options |
checkbox | The recipient checks or unchecks a box |
radio_group | The recipient selects one option from a group of mutually exclusive options |
Informational places
| Type | Description |
|---|---|
text | A static text value inserted on the document |
recipient_completed_date | The date the recipient completed their action |
envelope_completed_date | The date the envelope was completed by all recipients |
recipient_name | The recipient’s name |
recipient_email | The recipient’s email address |
Who fills a place
Every place except text and envelope_completed_date has a recipient_key that assigns it to one recipient. What a recipient can be assigned depends on its type:
| Recipient type | Signature places | Interactive places | Informational places |
|---|---|---|---|
signer | Yes, at least one | Yes | Yes |
preparer | No | Yes | Yes |
approver | No | Yes | Yes |
automatic_signer | Yes, at least one | No | Yes |
Preparers and approvers fill in the interactive places assigned to them, but never sign. An automatic signer has no ceremony, so it signs the signature and initials places assigned to it with the images you supply. Every signer and automatic signer needs at least one signature or initials place, or the API returns a no-signing-place error. A place assigned to a recipient type that can’t have it returns an incompatible-places error.
Positioning
Every place must be positioned on the document. There are two ways to do this:
- Placeholder: Embed
[[place_key]]in the document text. The place appears where the placeholder is found. - Fixed position: Specify exact coordinates using page number,
top, andleftvalues measured in points (1 point = 1/72 inch).
See Place Positioning for details.
{
"key": "employer_first_signature",
"type": "signature",
"recipient_key": "employer",
"height": 60
}{
"key": "employer_initials",
"type": "initials",
"recipient_key": "employer",
"height": 60
}{
"key": "buyer_email",
"type": "text_input",
"recipient_key": "buyer",
"capture_as": "buyer_email",
"prompt": "jane.doe@example.com",
"hint": "Please enter your email",
"format": "email",
"format_message": "Please enter a valid email address",
"requirement": "optional",
"width": 200,
"font_size": 8
}{
"key": "verification_code",
"type": "boxed_text_input",
"recipient_key": "signer",
"font_size": 12,
"width": 150,
"height": 20,
"box_count": 6,
"capture_as": "verification_code",
"prompt": null,
"hint": "Enter the 6-digit code from your email",
"requirement": "required"
}{
"key": "customer_comments",
"type": "multiline_text_input",
"recipient_key": "customer",
"capture_as": "comments",
"prompt": "Enter your comments here...",
"hint": "Please provide detailed feedback",
"requirement": "optional",
"width": 400,
"line_count": 5,
"line_height": 14,
"font_size": 10
}{
"key": "employment_type",
"type": "dropdown",
"recipient_key": "employee",
"options": [
{
"label": "Full-time",
"value": "full_time"
},
{
"label": "Part-time",
"value": "part_time"
},
{
"label": "Contract",
"value": "contract"
},
{
"label": "Internship",
"value": "internship"
}
],
"default": "Full-time",
"behavior": "auto",
"capture_as": "employment_type",
"prompt": "Select employment type",
"hint": "Choose the type of employment",
"requirement": "required",
"width": 150,
"font_size": 10
}{
"key": "receive_marketing_emails",
"type": "checkbox",
"recipient_key": "employee",
"symbol": "check",
"height": 10,
"capture_as": null
}{
"key": "billing_cycle",
"type": "radio_group",
"recipient_key": "customer",
"options": [
{
"value": "monthly"
},
{
"value": "annual"
}
],
"shape": "circle",
"symbol": "fill",
"default": "monthly",
"capture_as": "billing_cycle",
"requirement": "required",
"height": 20
}{
"key": "company_name",
"type": "text",
"value": "Acme Corp",
"font_size": 12,
"font_color": "#000000"
}{
"key": "employer_signed_at",
"type": "recipient_completed_date",
"recipient_key": "employer",
"date_format": "YYYY-MM-DD",
"font_size": 12
}{
"key": "signed_by_all_at",
"type": "envelope_completed_date",
"date_format": "MM/DD/YYYY HH:mm",
"font_size": 12
}{
"key": "client_name",
"type": "recipient_name",
"recipient_key": "client",
"font_size": 12
}{
"key": "client_email",
"type": "recipient_email",
"recipient_key": "client",
"font_size": 12
}