Captures

Some place types allow recipients to enter data during the ceremony, such as text input places. The entered data is rendered in the signed document. Captures let you also access that data via the API.

Defining captures

Places that accept recipient input have a capture_as property. Set it to a key name to store the entered value on the envelope’s captures object. Keys must be unique within the envelope.

For example, this text input place asks a recipient to enter an 8-digit reference number:

// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
    "documents": [
        {
            //...
            "places": [
                {
                    "key": "order_reference_number",
                    "type": "text_input",
                    "hint": "Your 8-digit reference code",
                    "format": "/^[0-9]{8}$/",
                    "recipient_key": "customer",
                    "capture_as": "reference"
                }
            ]
        }
    ],
    "recipients": [
        //...
    ],
    "title": "Order Confirmation"
}

When the recipient completes the ceremony, the entered value is stored in the captures object on the envelope:

// HTTP/1.1 200 OK
{
    "id": "55072f0e-b919-4d69-89cd-e7e56af00530",
    //...
    "captures": {
        "reference": "11223344"
    }
}

More examples

// Request places
[
  {
    "key": "ssn_last_four",
    "type": "text_input",
    "recipient_key": "applicant",
    "capture_as": "ssn_last_4",
    "format": "/^[0-9]{4}$/",
    "requirement": "required"
  },
  {
    "key": "phone_number",
    "type": "text_input",
    "recipient_key": "applicant",
    "capture_as": "phone",
    "requirement": "required"
  }
]

// Response captures
{
  "captures": {
    "ssn_last_4": "1234",
    "phone": "555-123-4567"
  }
}