Industries
Embed Policy Signing in Your Portal
Create a policy application envelope for a policyholder who is already signed in to your portal, then show the signing ceremony inside your app.
A policyholder is already logged in to your portal when they reach the application step. Emailing them a link would send them away and ask them to prove who they are a second time. Instead, create the envelope without an invitation email and show the ceremony inside your own page.
Envelope shape
- One PDF document with two places. A required
checkboxfor the disclosure acknowledgement and asignature. Both belong to thepolicyholderrecipient. See Checkbox. - Captured answer.
capture_as: disclosure_ackstores the checkbox value in the envelope’scaptures. See Captures. delivery_type: none. SignatureAPI does not email the signed documents to the policyholder. Your portal shows or stores them. See Recipient object.- Metadata and topics.
metadata.application_idlinks the envelope to the application in your system.
Routing
There is one signer, so the envelope uses the default sequential routing. The checkbox is a form place, and form places need sequential routing.
The example then creates the ceremony with POST /v1/recipients/{recipient_id}/ceremonies, using custom authentication. The call returns a ceremony url that your portal can display. Set embeddable_in to the origins that may frame it, and describe how your app authenticated the user in the authentication entry. See Custom authentication and the embedded signing guide. Create the ceremony only after the envelope is in_progress.
Webhooks to listen for
envelope.started: the envelope isin_progress, so you can create the ceremony.recipient.completed: the policyholder signed. In the browser, theceremony.completedmessage only updates your UI. Confirm the result from this webhook on your server.deliverable.generated: the signed application and audit log are ready. Download them and store them with the policy file.
Set up the endpoint as shown in Set up webhooks.
Compliance notes
This is general information, not legal advice. Rules on electronic signatures and disclosures for insurance differ by jurisdiction and line of business, so have counsel review your documents and process. Do not put health or payment-card data in metadata, document data or captures unless your own review allows it.
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Policy Application (sample)",
"metadata": {
"application_id": "app_6620"
},
"topics": [
"insurance",
"policy_applications"
],
"documents": [
{
"key": "policy_application",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "disclosure_ack",
"page": 1,
"top": 140,
"left": 210
},
{
"place_key": "policyholder_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "disclosure_ack",
"type": "checkbox",
"recipient_key": "policyholder",
"requirement": "required",
"capture_as": "disclosure_ack"
},
{
"key": "policyholder_signature",
"type": "signature",
"recipient_key": "policyholder"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "policyholder",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"delivery_type": "none"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Policy Application (sample)",
"metadata": {
"application_id": "app_6620"
},
"topics": [
"insurance",
"policy_applications"
],
"documents": [
{
"key": "policy_application",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "disclosure_ack",
"page": 1,
"top": 140,
"left": 210
},
{
"place_key": "policyholder_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "disclosure_ack",
"type": "checkbox",
"recipient_key": "policyholder",
"requirement": "required",
"capture_as": "disclosure_ack"
},
{
"key": "policyholder_signature",
"type": "signature",
"recipient_key": "policyholder"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "policyholder",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"delivery_type": "none"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Policy Application (sample)",
"metadata": {
"application_id": "app_6620"
},
"topics": [
"insurance",
"policy_applications"
],
"documents": [
{
"key": "policy_application",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"format": "pdf",
"fixed_positions": [
{
"place_key": "disclosure_ack",
"page": 1,
"top": 140,
"left": 210
},
{
"place_key": "policyholder_signature",
"page": 1,
"top": 172,
"left": 210
}
],
"places": [
{
"key": "disclosure_ack",
"type": "checkbox",
"recipient_key": "policyholder",
"requirement": "required",
"capture_as": "disclosure_ack"
},
{
"key": "policyholder_signature",
"type": "signature",
"recipient_key": "policyholder"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "policyholder",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"delivery_type": "none"
}
]
}
}{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Policy Application (sample)",
"label": null,
"message": null,
"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": [
"policy_application"
]
},
"metadata": {
"application_id": "app_6620"
},
"sender": {
"name": "Acme Corp Legal",
"email": "legal@acme.example",
"organization": "Acme Corp"
},
"captures": {
"disclosure_ack": false
},
"documents": [
{
"id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"key": "policy_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": "disclosure_ack"
},
{
"page": 1,
"top": 172,
"left": 210,
"place_key": "policyholder_signature"
}
],
"places": [
{
"key": "disclosure_ack",
"type": "checkbox",
"recipient_key": "policyholder",
"height": 20,
"symbol": "check",
"capture_as": "disclosure_ack",
"requirement": "required"
},
{
"key": "policyholder_signature",
"type": "signature",
"recipient_key": "policyholder",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_HVl3Nj7XzTzX7jN3lVH5vn",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "policyholder",
"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": "none",
"signature_options": [
"typed",
"drawn"
],
"status": "pending",
"status_updated_at": "2026-11-02T14:03:11.000Z",
"completed_at": null
}
],
"topics": [
"insurance",
"policy_applications"
],
"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.