Skip to content

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_date place prints when the supplier completed. It needs a recipient_key and 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_number is returned on every event, and the purchase_orders topic 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.

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"
    }
  ]
}
{
  "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
}

Errors every call can return are in Errors and Authentication.