> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Captures

> Retrieve data entered by recipients during signing ceremonies through the API

Some [place](/docs/api/resources/places/object) types allow recipients to enter data during the [ceremony](/docs/api/resources/ceremonies/object), such as [text input places](/docs/api/resources/places/text-input). 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:

```json theme={null}
// 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:

```json theme={null}
// HTTP Status Code 200

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

## More examples

<CodeGroup>
  ```json Multiple text captures theme={null}
  // 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"
    }
  }
  ```

  ```json Checkbox capture theme={null}
  // Request places
  [
    {
      "key": "accept_terms",
      "type": "checkbox",
      "recipient_key": "customer",
      "capture_as": "terms_accepted",
      "requirement": "required"
    },
    {
      "key": "marketing_opt_in",
      "type": "checkbox",
      "recipient_key": "customer",
      "capture_as": "marketing_consent"
    }
  ]

  // Response captures
  {
    "captures": {
      "terms_accepted": true,
      "marketing_consent": false
    }
  }
  ```

  ```json Dropdown capture theme={null}
  // Request places
  [
    {
      "key": "state_selection",
      "type": "dropdown",
      "recipient_key": "applicant",
      "options": "us_states_2_letter_codes",
      "capture_as": "state",
      "requirement": "required"
    }
  ]

  // Response captures
  {
    "captures": {
      "state": "CA"
    }
  }
  ```
</CodeGroup>