Skip to content

Cookbook

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.

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.

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
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.

Capture a reference number
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"
    }
  ]
}
{
  "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
}

Errors every call can return are in Errors and Authentication.