---
title: "Place Object"
description: "Define signature fields, input areas, and auto-filled values at specific locations in documents"
canonical: "https://signatureapi.com/docs/api/resources/places/object"
source: "https://signatureapi.com/docs/api/resources/places/object.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T11:48:11Z"
---

# Place Object

Define signature fields, input areas, and auto-filled values at specific locations in documents

_Last verified against API version 1.18.0._

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](https://signatureapi.com/docs/api/resources/documents/object). 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](https://signatureapi.com/docs/api/resources/documents/object).

> **Tip:** To generate a document from a template with dynamic data before any recipient signs, use [Document Templates](https://signatureapi.com/docs/api/resources/documents/templates) instead.

## 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`](https://signatureapi.com/docs/api/resources/places/signature) | The recipient draws or types their signature |
| [`initials`](https://signatureapi.com/docs/api/resources/places/initials)   | The recipient enters their initials          |

### Interactive places

Interactive places require [sequential routing](https://signatureapi.com/docs/api/resources/envelopes/routing).

| Type                                                                                              | Description                                                                 |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [`text_input`](https://signatureapi.com/docs/api/resources/places/text-input)                     | The recipient types free-form text                                          |
| [`boxed_text_input`](https://signatureapi.com/docs/api/resources/places/boxed-text-input)         | The recipient enters text into individual character boxes                   |
| [`multiline_text_input`](https://signatureapi.com/docs/api/resources/places/multiline-text-input) | The recipient types text across multiple lines                              |
| [`dropdown`](https://signatureapi.com/docs/api/resources/places/dropdown)                         | The recipient selects from a list of options                                |
| [`checkbox`](https://signatureapi.com/docs/api/resources/places/checkbox)                         | The recipient checks or unchecks a box                                      |
| [`radio_group`](https://signatureapi.com/docs/api/resources/places/radio-group)                   | The recipient selects one option from a group of mutually exclusive options |

### Informational places

| Type                                                                                                           | Description                                           |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [`text`](https://signatureapi.com/docs/api/resources/places/text)                                              | A static text value inserted on the document          |
| [`recipient_completed_date`](https://signatureapi.com/docs/api/resources/places/date#recipient-completed-date) | The date the recipient completed their action         |
| [`envelope_completed_date`](https://signatureapi.com/docs/api/resources/places/date#envelope-completed-date)   | The date the envelope was completed by all recipients |
| [`recipient_name`](https://signatureapi.com/docs/api/resources/places/recipient-name)                          | The recipient's name                                  |
| [`recipient_email`](https://signatureapi.com/docs/api/resources/places/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`](https://signatureapi.com/docs/api/resources/recipients/signer)                     | Yes, at least one | Yes                | Yes                  |
| [`preparer`](https://signatureapi.com/docs/api/resources/recipients/preparer)                 | No                | Yes                | Yes                  |
| [`approver`](https://signatureapi.com/docs/api/resources/recipients/approver)                 | No                | Yes                | Yes                  |
| [`automatic_signer`](https://signatureapi.com/docs/api/resources/recipients/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](https://signatureapi.com/docs/v1/errors/no-signing-place) error. A place assigned to a recipient type that can't have it returns an [incompatible-places](https://signatureapi.com/docs/v1/errors/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`, and `left` values measured in points (1 point = 1/72 inch).

See [Place Positioning](https://signatureapi.com/docs/api/resources/places/positioning) for details.

### Example: Signature

Response 200 OK:

```json
{
  "key": "employer_first_signature",
  "type": "signature",
  "recipient_key": "employer",
  "height": 60
}
```

### Example: Initials

Response 200 OK:

```json
{
  "key": "employer_initials",
  "type": "initials",
  "recipient_key": "employer",
  "height": 60
}
```

### Example: Text input

Response 200 OK:

```json
{
  "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
}
```

### Example: Boxed text input

Response 200 OK:

```json
{
  "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"
}
```

### Example: Multiline text input

Response 200 OK:

```json
{
  "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
}
```

### Example: Dropdown

Response 200 OK:

```json
{
  "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
}
```

### Example: Checkbox

Response 200 OK:

```json
{
  "key": "receive_marketing_emails",
  "type": "checkbox",
  "recipient_key": "employee",
  "symbol": "check",
  "height": 10,
  "capture_as": null
}
```

### Example: Radio group

Response 200 OK:

```json
{
  "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
}
```

### Example: Text

Response 200 OK:

```json
{
  "key": "company_name",
  "type": "text",
  "value": "Acme Corp",
  "font_size": 12,
  "font_color": "#000000"
}
```

### Example: Recipient completed date

Response 200 OK:

```json
{
  "key": "employer_signed_at",
  "type": "recipient_completed_date",
  "recipient_key": "employer",
  "date_format": "YYYY-MM-DD",
  "font_size": 12
}
```

### Example: Envelope completed date

Response 200 OK:

```json
{
  "key": "signed_by_all_at",
  "type": "envelope_completed_date",
  "date_format": "MM/DD/YYYY HH:mm",
  "font_size": 12
}
```

### Example: Recipient name

Response 200 OK:

```json
{
  "key": "client_name",
  "type": "recipient_name",
  "recipient_key": "client",
  "font_size": 12
}
```

### Example: Recipient email

Response 200 OK:

```json
{
  "key": "client_email",
  "type": "recipient_email",
  "recipient_key": "client",
  "font_size": 12
}
```
