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.
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);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 "", 200Checkbox captures are true or false, and a place the signer left empty is null, so handle null before you store a value.
Related
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"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"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"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"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
}{
"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 every call can return are in Errors and Authentication.