Cookbook
Invoice approval flow
Send an invoice to an approver first and to a signer only after the approval, with one sequential envelope and an approver recipient.
Route an invoice through a finance manager’s approval before the CFO signs it. The approver reviews and approves. The signer receives the document only after that.
The sample PDF stands in for your invoice. Your own metadata links the envelope back to your records.
- Order is the array order. With
routingset tosequential, the approver is first, so the signer is notified only after the approver completes. See sequential signing. - The approver needs no place. Only the signer has a signature place. An approver has no
delivery_typeemail by default. See Approver. - Metadata and topics.
metadatacomes back on every event asenvelope_metadata, andtopicslets a webhook endpoint receive only invoice envelopes.
Know the outcome
Subscribe a webhook endpoint to recipient.completed and recipient.rejected, and read data.recipient_key. A recipient.completed event with the key finance_manager means the invoice is approved. A recipient.rejected event means that recipient declined, and data.reason holds their explanation. A rejection does not cancel the envelope: replace the recipient or cancel the envelope.
Related
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Invoice INV-2041",
"message": "Please review invoice INV-2041 for approval.",
"routing": "sequential",
"topics": [
"invoices"
],
"metadata": {
"invoice_number": "INV-2041",
"amount": "4800.00"
},
"documents": [
{
"key": "invoice",
"title": "Invoice INV-2041",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "cfo"
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "finance_manager",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "cfo",
"name": "Maria Garcia",
"email": "maria.garcia@example.com"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Invoice INV-2041",
"message": "Please review invoice INV-2041 for approval.",
"routing": "sequential",
"topics": [
"invoices"
],
"metadata": {
"invoice_number": "INV-2041",
"amount": "4800.00"
},
"documents": [
{
"key": "invoice",
"title": "Invoice INV-2041",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "cfo"
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "finance_manager",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "cfo",
"name": "Maria Garcia",
"email": "maria.garcia@example.com"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Invoice INV-2041",
"message": "Please review invoice INV-2041 for approval.",
"routing": "sequential",
"topics": [
"invoices"
],
"metadata": {
"invoice_number": "INV-2041",
"amount": "4800.00"
},
"documents": [
{
"key": "invoice",
"title": "Invoice INV-2041",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "cfo"
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "finance_manager",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "cfo",
"name": "Maria Garcia",
"email": "maria.garcia@example.com"
}
]
}
}{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Invoice INV-2041",
"label": null,
"message": "Please review invoice INV-2041 for approval.",
"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": [
"invoices"
],
"metadata": {
"invoice_number": "INV-2041",
"amount": "4800.00"
},
"documents": [
{
"id": "doc_4YvlxUZN28CeonDq6rTbvk",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"key": "invoice",
"title": "Invoice INV-2041",
"page_count": 2,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"fixed_positions": [],
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "cfo",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_49r1R2jpPDz8hSpP75ZkPp",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "approver",
"key": "finance_manager",
"name": "Alex Chen",
"email": "alex.chen@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": "none",
"ceremony_creation": "automatic",
"completed_at": null,
"status_updated_at": "2026-11-02T14:03:11.000Z"
},
{
"id": "re_4VP9v4uPj6jwZzQ14CG2O8",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "cfo",
"name": "Maria Garcia",
"email": "maria.garcia@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": [
"invoice"
],
"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.