---
title: "Push captured signer input into your database"
description: "Collect values signers type into places with capture_as, then read the envelope when it completes and upsert the values into your database."
canonical: "https://signatureapi.com/docs/cookbook/captures-to-database"
source: "https://signatureapi.com/docs/cookbook/captures-to-database.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:17:27Z"
---

# Push captured signer input into your database

Collect values signers type into places with capture_as, then read the envelope when it completes and upsert the values into your database.

_Last verified against API version 1.18.0._

Ask the signer for a value while they sign, such as an order reference, and store it in your database when the envelope completes.

`capture_as` on the text input names the value. When the signer completes, it appears in the envelope's `captures` object under that name (here, `reference`). Form places such as text inputs, checkboxes and dropdowns are allowed only in `sequential` envelopes, which is the default.

## Store it on completion

Subscribe an endpoint to `envelope.completed`, fetch the envelope, and upsert by envelope id so a repeated event writes the same row.

```javascript Node.js
import express from "express";
import pg from "pg";
import { Webhook } from "standardwebhooks";

const db = new pg.Pool();
const wh = new Webhook(process.env.SIGNATUREAPI_WEBHOOK_SECRET);
const app = express();

app.post("/webhooks/signatureapi", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = wh.verify(req.body.toString("utf8"), req.headers);
  } catch {
    return res.sendStatus(400);
  }
  if (event.type !== "envelope.completed") return res.sendStatus(200);

  const api = await fetch(`https://api.signatureapi.com/v1/envelopes/${event.data.envelope_id}`, {
    headers: { "X-API-Key": process.env.SIGNATUREAPI_KEY },
  });
  if (!api.ok) return res.sendStatus(500); // SignatureAPI retries the event
  const envelope = await api.json();

  await db.query(
    `INSERT INTO signing_records (envelope_id, order_id, reference, completed_at)
     VALUES ($1, $2, $3, $4)
     ON CONFLICT (envelope_id) DO UPDATE SET reference = EXCLUDED.reference`,
    [envelope.id, envelope.metadata.order_id, envelope.captures.reference, envelope.completed_at],
  );
  res.sendStatus(200);
});

app.listen(3000);
```

```python Python
import os

import psycopg
import requests
from flask import Flask, request
from standardwebhooks import Webhook

wh = Webhook(os.environ["SIGNATUREAPI_WEBHOOK_SECRET"])
app = Flask(__name__)


@app.post("/webhooks/signatureapi")
def handle():
    try:
        event = wh.verify(request.get_data(), dict(request.headers))
    except Exception:
        return "", 400
    if event["type"] != "envelope.completed":
        return "", 200

    api = requests.get(
        f"https://api.signatureapi.com/v1/envelopes/{event['data']['envelope_id']}",
        headers={"X-API-Key": os.environ["SIGNATUREAPI_KEY"]},
    )
    if not api.ok:
        return "", 500  # SignatureAPI retries the event
    envelope = api.json()

    with psycopg.connect(os.environ["DATABASE_URL"]) as conn:
        conn.execute(
            """INSERT INTO signing_records (envelope_id, order_id, reference, completed_at)
               VALUES (%s, %s, %s, %s)
               ON CONFLICT (envelope_id) DO UPDATE SET reference = EXCLUDED.reference""",
            (envelope["id"], envelope["metadata"]["order_id"], envelope["captures"]["reference"], envelope["completed_at"]),
        )
    return "", 200
```

Checkbox captures are `true` or `false`, and a place the signer left empty is `null`, so handle `null` before you store a value.

## Related

- [Captures](https://signatureapi.com/docs/api/resources/envelopes/captures)
- [Store envelope data on completion](https://signatureapi.com/docs/api/guides/use-cases/store-data-webhook)
- [Text input place](https://signatureapi.com/docs/api/resources/places/text-input)

### Example: Capture a reference number

The signer types a reference number. It is returned in captures.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Order Confirmation",
  "metadata": {
    "order_id": "ORD-2026-1234"
  },
  "documents": [
    {
      "key": "order",
      "title": "Order Confirmation",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "reference_number",
          "page": 2,
          "top": 600,
          "left": 72
        }
      ],
      "places": [
        {
          "key": "signer_signs_here",
          "type": "signature",
          "recipient_key": "customer"
        },
        {
          "key": "reference_number",
          "type": "text_input",
          "recipient_key": "customer",
          "hint": "Your 8-digit reference code",
          "capture_as": "reference",
          "width": 200
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "customer",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Order Confirmation",
  "label": null,
  "message": null,
  "status": "processing",
  "mode": "test",
  "routing": "sequential",
  "language": "en",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "attestation": "none",
  "branding": {
    "logo": null,
    "accent_color": "#2463eb",
    "email": {
      "from": "noreply@signatureapi.com",
      "footer": null,
      "logo_position": "left"
    }
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "topics": [],
  "metadata": {
    "order_id": "ORD-2026-1234"
  },
  "documents": [
    {
      "id": "doc_4YvlxUZN28CeonDq6rTbvk",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "order",
      "title": "Order Confirmation",
      "page_count": 2,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "reference_number",
          "page": 2,
          "top": 600,
          "left": 72
        }
      ],
      "places": [
        {
          "key": "signer_signs_here",
          "type": "signature",
          "recipient_key": "customer",
          "height": 60
        },
        {
          "key": "reference_number",
          "type": "text_input",
          "recipient_key": "customer",
          "hint": "Your 8-digit reference code",
          "capture_as": "reference",
          "width": 200,
          "requirement": "required",
          "font_size": 12,
          "prompt": null,
          "format": null,
          "format_message": null
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_49r1R2jpPDz8hSpP75ZkPp",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "customer",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "status": "pending",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "redirect_url": null,
        "redirect_delay": 3,
        "embeddable_in": [],
        "url_variant": "standard",
        "url": null
      },
      "delivery_type": "email",
      "ceremony_creation": "automatic",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "completed_at": null,
      "status_updated_at": "2026-11-02T14:03:11.000Z"
    }
  ],
  "deliverable": {
    "id": "del_6FF89lKNyTNamOJCJd1tLL",
    "name": null,
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "type": "standard",
    "status": "pending",
    "url": null,
    "language": "en",
    "timezone": "UTC",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "order"
    ],
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null
  },
  "captures": {},
  "snapshot_url": null,
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains validation errors.",
  "errors": [
    "recipients[0].email must be a valid email address"
  ]
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
