Places

Places are designated areas within a document where a recipient either provides input, such as a signature, or where a constant or calculated value is added, like a completion date.

To define a place, you need to specify both a place object and a position, either by using a placeholder within the document or by setting fixed positions with coordinates.

​

Place Objects

Places are defined in the places array within the document object. Each element in the array represents a place within the document. The properties of each place depend on its type. For example, a signature place will include information about the recipient expected to sign, while a date place, such as envelope completed date, can specify the format for the date-time string.

"documents":
[
  {
    ...
    "places": [
      {
        "key": "employee_signs_here",
        "type": "signature",
        "recipient_key": "employee"
      },
      {
        "key": "manager_signs_here",
        "type": "signature",
        "recipient_key": "manager"
      },
      {
        "key": "completed_at",
        "type": "envelope_completed_at",
        "date_format": "DD MMMM YYYY, HH:mm"
      }
    ]
    ...
  }
]

​

Place Types

There are several types of places that can be defined within a document:

• Signature
• Recipient Completed Date
• Envelope Completed Date
• Text

​

Signature

This marks a specific area in the document where the recipient, as identified by the recipient_key, can place their signature.

For example, this is a definition of a signature place for the recipient with key employer:

"documents":
[
  {
    ...
    "places": [
      {
        "key": "employer_first_signature",
        "type": "signature",
        "recipient_key": "employer"
      }
    ]
    ...
  }
]

​

Recipient Completed Date

This designates an area within the document to record the date when the recipient, identified by recipient_key, completed their action (for example, signing) within the envelope.

For example, this is how to define a recipient completed date place for the recipient with the key employer and the date format YYYY-MM-DD:

"documents":
[
  {
    ...
    "places": [
      {
        "key": "employer_signed_at",
        "type": "recipient_completed_date",
        "recipient_key": "employer",
        "date_format": "YYYY-MM-DD"
      }
    ]
    ...
  }
]

​

Envelope Completed Date

This indicates a location within the document to capture the date when the entire envelope was completed, meaning all recipients have completed their actions (for example, signing).

For example, this is how to define a place for the envelope completed date with the key employer and the date format MM/DD/YYYY, HH:MM:SS:

"documents":
[
  {
    ...
    "places": [
      {
        "key": "signed_by_all_at",
        "type": "envelope_completed_date",
        "date_format": "MM/DD/YYYY, HH:MM:SS"
      }
    ]
    ...
  }
]

​

Text

Text places let you insert a specific string at a location in the document.

For example, this sets the value Lorem Ipsum Ltd for the place with key company_name.

"documents":
[
  {
    ...
    "places": [
      {
        "key": "company_name",
        "type": "text",
        "value": "Lorem Ipsum Ltd"
      }
    ]
    ...
  }
]

​

Place Positioning

Places can be positioned in the document using either a placeholder or a fixed position.

​

Placeholders

You can define placeholders in the document using the template [[place_key]], where place_key corresponds to the key of the place.

For example, to define placeholders for two places with the keys licensor_signs_here and licensor_signed_at in the document:

If licensor_signs_here is defined as a signature, the recipient’s signature will appear over the placeholder. Similarly, if licensor_signed_at is defined as recipient_completed_date, the date will appear over the placeholder.

You can set the text color of the placeholder to white to hide it from recipients.

​

Fixed Positions

Fixed positions can be defined by specifying the page number, along with distances from the top of the page (top) and from the left side of the page (left).

Both top and left are measured in points (1/72 of an inch).

For example, to define a fixed position for a place with the key employer_first_signature, located 1 inch from the left and 5 inches from the top of the page:

"documents":
[
  {
    ...
    "fixed_positions": [
      {
        "place_key": "employer_first_signature",
        "page": 2,
        "top": 360,
        "left": 72
      }
    ]
    ...
  }
]

Each place is positioned on the page based on the coordinates of its bottom-left corner, as shown in the image below.

​

Legacy Signature Places

We previously defined signature places using placeholders like [[employee.signature]], which we now refer to as Legacy Signature Places. We now recommend using the more flexible Place objects, as well as placeholders or fixed positions, described above. If you’re already using Legacy Signature Places, don’t worry— we’ll continue to support them.

For Power Automate integration, Legacy Signature Places are currently the only supported method.