Use Placeholders to Position Signatures

In SignatureAPI, places are areas in a document where recipients sign, enter information, or where details, such as dates, are automatically added. The signature place is one of such places.

There are two ways to position places: fixed positions (coordinates) and placeholders within the document. In this example, we will show how to position a signature place using a placeholder.

For this example, we will create an envelope with:

• One recipient (of type signer), identified with the key visitor.
• The visitor signs a single PDF document.
• The document will have one signature place, identified with the key signer_signs_here, that will be signed by the recipient visitor.

All other envelope settings use the default configuration:

• The recipient will receive an email with a link to sign.
• The account’s default language, timezone, and timestamp format used.

Prepare your Document

Placeholders are text within your PDF document that define the location where places (such as signatures, initials, text inputs, etc.) should appear. They follow the format [[place_key]], where place_key identifies the place within the document.

For this example, we prepared a document that contains the placeholder [[signer_signs_here]] to indicate the position of the place with the key signer_signs_here.

Create the Envelope

When creating the envelope, add the signature place object to the places array inside the document object, with the following properties:

• key: This identifies the place within the document. Must match what’s inside the square brackets in the placeholder inside the document file, in this case: signer_signs_here.
• type: As this is a signature place, we use the value signature.
• recipient_key: The key of the recipient that will sign in this place. In this example, there is just one recipient, who has the key visitor.

// POST https://api.signatureapi.com/v1/envelopes
// X-Api-Key: <Your API Key>
{
  "title": "Dummy Consent",
  "message": "Please review and sign the Dummy Privacy Policy for internal testing purposes. This document is not legally binding and is used solely for demonstration\n\nThank you for your cooperation.",
  "documents": [
    {
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
      "places": [
        {
          "key": "signer_signs_here",
          "type": "signature",
          "recipient_key": "visitor"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "visitor",
      "name": "John Doe",
      "email": "john@example.com"
    }
  ]
}

Result

If the request is successful, SignatureAPI will send John Doe (the recipient) an email with a link to sign. John will click the link and will be able to place his signature on top of the signature line.

Try It

Try this example in Postman using your test API key to create a free, non-binding test envelope. Test envelopes won’t send emails, but you can review them in your dashboard.

Keep Learning

• Learn how to position a signature using coordinates when exact positioning is required.
• Explore other types of places, such as initials, text inputs, or completion dates.