Cookbook
Purchase order approval and supplier signature
Have procurement approve a purchase order, then send it to the supplier to sign and date, in one sequential envelope with an approver and a signer.
Procurement approves the order internally. Then the supplier signs it, and the date of signing is printed next to the signature.
- Approver first. The approver is listed before the supplier, so the supplier receives nothing until procurement approves.
- The date is a place. The
recipient_completed_dateplace prints when the supplier completed. It needs arecipient_keyand no input from the signer. The sample PDF has a placeholder only for the signature, so the date gets a fixed position beside it. See Date places. - Find the order later.
metadata.po_numberis returned on every event, and thepurchase_orderstopic routes events to one webhook endpoint. See Topics.
When the supplier signs, SignatureAPI generates the signed PDF. To store it, see archive signed documents or the download guide.
Related
Buyer approves, supplier signs
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Purchase Order PO-7733",
"message": "Please review and sign purchase order PO-7733.",
"routing": "sequential",
"topics": [
"purchase_orders"
],
"metadata": {
"po_number": "PO-7733",
"supplier_id": "sup_204"
},
"documents": [
{
"key": "purchase_order",
"title": "Purchase Order PO-7733",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "signed_on",
"page": 2,
"top": 474,
"left": 300
}
],
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "supplier"
},
{
"key": "signed_on",
"type": "recipient_completed_date",
"recipient_key": "supplier"
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "procurement",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "supplier",
"name": "John Smith",
"email": "john.smith@example.com"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Purchase Order PO-7733",
"message": "Please review and sign purchase order PO-7733.",
"routing": "sequential",
"topics": [
"purchase_orders"
],
"metadata": {
"po_number": "PO-7733",
"supplier_id": "sup_204"
},
"documents": [
{
"key": "purchase_order",
"title": "Purchase Order PO-7733",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "signed_on",
"page": 2,
"top": 474,
"left": 300
}
],
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "supplier"
},
{
"key": "signed_on",
"type": "recipient_completed_date",
"recipient_key": "supplier"
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "procurement",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "supplier",
"name": "John Smith",
"email": "john.smith@example.com"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Purchase Order PO-7733",
"message": "Please review and sign purchase order PO-7733.",
"routing": "sequential",
"topics": [
"purchase_orders"
],
"metadata": {
"po_number": "PO-7733",
"supplier_id": "sup_204"
},
"documents": [
{
"key": "purchase_order",
"title": "Purchase Order PO-7733",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "signed_on",
"page": 2,
"top": 474,
"left": 300
}
],
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "supplier"
},
{
"key": "signed_on",
"type": "recipient_completed_date",
"recipient_key": "supplier"
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "procurement",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "supplier",
"name": "John Smith",
"email": "john.smith@example.com"
}
]
}
}{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Purchase Order PO-7733",
"label": null,
"message": "Please review and sign purchase order PO-7733.",
"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": [
"purchase_orders"
],
"metadata": {
"po_number": "PO-7733",
"supplier_id": "sup_204"
},
"documents": [
{
"id": "doc_4YvlxUZN28CeonDq6rTbvk",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"key": "purchase_order",
"title": "Purchase Order PO-7733",
"page_count": 2,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "signed_on",
"page": 2,
"top": 474,
"left": 300
}
],
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "supplier",
"height": 60
},
{
"key": "signed_on",
"type": "recipient_completed_date",
"recipient_key": "supplier",
"date_format": "D MMM YYYY",
"font_size": 12
}
]
}
],
"recipients": [
{
"id": "re_49r1R2jpPDz8hSpP75ZkPp",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "approver",
"key": "procurement",
"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": "supplier",
"name": "John Smith",
"email": "john.smith@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": [
"purchase_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.