Skip to content

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 routing set to sequential, 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_type email by default. See Approver.
  • Metadata and topics. metadata comes back on every event as envelope_metadata, and topics lets 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.

Approver, then signer
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"
    }
  ]
}
{
  "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
}

Errors every call can return are in Errors and Authentication.