Skip to content

Industries

Collect Attestations With an Official Approver

Collect a signed permit application with a validated reference number, then route it to an official who approves it, with a pointer to qualified signatures.

A permit application has a reference number that must be in the right format, a signature from the applicant, and a sign-off from an official. Counter visits and scanned PDFs make all three slow. This envelope validates the reference while the applicant types it, collects the signature, and then asks the official to approve.

Envelope shape

  • Validated text input. permit_ref uses format: "/^[A-Z]{2}-[0-9]{6}$/". A format_message appears when the value does not match, and capture_as stores the accepted value. See Text input.
  • Applicant as signer. The applicant has the permit_ref and signature places.
  • Official as approver. The official is an approver. Approvers can fill input places, but cannot have signature or initials places, so this recipient has none. See Approver.
  • Metadata and topics. metadata.permit_id and topics tie the envelope to your case system. See Topics.

Routing

The envelope uses sequential routing. The applicant signs first, then the official receives the application to approve. The text input is a form place, and form places need sequential routing. See Send to an approver.

Webhooks to listen for

  • recipient.completed: fires when the applicant signs and again when the official approves. Check recipient_type and envelope_metadata.permit_id to update the case.
  • recipient.rejected: the official declined and may include a reason. The envelope stays open, so reopen the case or cancel the envelope.
  • envelope.completed: the application is signed and approved.
  • deliverable.generated: download the signed application and audit log for the case file.

Compliance notes

This is general information, not legal advice. A standard signer produces a simple electronic signature. Some public procedures require a qualified electronic signature instead. For that, see What are qualified signatures? and the qualified signer recipient. Whether a given procedure accepts either kind of signature depends on the authority and its rules, so confirm that with counsel or the authority. Keep personal data out of metadata, which appears in webhook payloads.

Default
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Permit Application (sample)",
  "message": "Please enter your permit reference and sign the application.",
  "routing": "sequential",
  "metadata": {
    "permit_id": "permit_4410"
  },
  "topics": [
    "public_sector",
    "permits"
  ],
  "documents": [
    {
      "key": "permit_application",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "permit_ref",
          "page": 1,
          "top": 140,
          "left": 210
        },
        {
          "place_key": "applicant_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "permit_ref",
          "type": "text_input",
          "recipient_key": "applicant",
          "prompt": "Permit reference",
          "hint": "Format: AB-123456",
          "format": "/^[A-Z]{2}-[0-9]{6}$/",
          "format_message": "Use two capital letters, a dash and six digits",
          "width": 160,
          "capture_as": "permit_ref"
        },
        {
          "key": "applicant_signature",
          "type": "signature",
          "recipient_key": "applicant"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "applicant",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    },
    {
      "type": "approver",
      "key": "official",
      "name": "Alex Chen",
      "email": "alex.chen@example.com"
    }
  ]
}
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Permit Application (sample)",
  "label": null,
  "message": "Please enter your permit reference and sign the application.",
  "status": "processing",
  "attestation": "none",
  "language": "en",
  "mode": "test",
  "routing": "sequential",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "snapshot_url": null,
  "branding": {
    "logo": null,
    "accent_color": "#2463EB",
    "email": {
      "footer": null,
      "logo_position": "left",
      "from": "noreply@signatureapi.com"
    }
  },
  "deliverable": {
    "id": "del_HVl3Nj7XzTzX7jN3lVH5vn",
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "name": null,
    "status": "pending",
    "type": "standard",
    "url": null,
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null,
    "timezone": "UTC",
    "language": "en",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "permit_application"
    ]
  },
  "metadata": {
    "permit_id": "permit_4410"
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "captures": {
    "permit_ref": null
  },
  "documents": [
    {
      "id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "permit_application",
      "title": null,
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "page": 1,
          "top": 140,
          "left": 210,
          "place_key": "permit_ref"
        },
        {
          "page": 1,
          "top": 172,
          "left": 210,
          "place_key": "applicant_signature"
        }
      ],
      "places": [
        {
          "key": "permit_ref",
          "type": "text_input",
          "recipient_key": "applicant",
          "capture_as": "permit_ref",
          "hint": "Format: AB-123456",
          "format": "/^[A-Z]{2}-[0-9]{6}$/",
          "prompt": "Permit reference",
          "requirement": "required",
          "format_message": "Use two capital letters, a dash and six digits",
          "font_size": 12,
          "width": 160
        },
        {
          "key": "applicant_signature",
          "type": "signature",
          "recipient_key": "applicant",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "applicant",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "redirect_delay": 3,
        "url": null,
        "url_variant": "standard"
      },
      "ceremony_creation": "automatic",
      "delivery_type": "email",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "status": "pending",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    },
    {
      "id": "re_OcsAUqEe6a6eEqUAscOC2u",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "approver",
      "key": "official",
      "email": "alex.chen@example.com",
      "name": "Alex Chen",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "redirect_delay": 3,
        "url": null,
        "url_variant": "standard"
      },
      "ceremony_creation": "automatic",
      "delivery_type": "none",
      "status": "awaiting",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    }
  ],
  "topics": [
    "public_sector",
    "permits"
  ],
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}

Errors every call can return are in Errors and Authentication.