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_refusesformat: "/^[A-Z]{2}-[0-9]{6}$/". Aformat_messageappears when the value does not match, andcapture_asstores the accepted value. See Text input. - Applicant as signer. The
applicanthas thepermit_refandsignatureplaces. - Official as approver. The
officialis anapprover. Approvers can fill input places, but cannot have signature or initials places, so this recipient has none. See Approver. - Metadata and topics.
metadata.permit_idandtopicstie 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. Checkrecipient_typeandenvelope_metadata.permit_idto update the case.recipient.rejected: the official declined and may include areason. 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.
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"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"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"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"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
}{
"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.