Skip to content

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 checkbox for the disclosure acknowledgement and a signature. Both belong to the policyholder recipient. See Checkbox.
  • Captured answer. capture_as: disclosure_ack stores the checkbox value in the envelope’s captures. 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_id links 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 is in_progress, so you can create the ceremony.
  • recipient.completed: the policyholder signed. In the browser, the ceremony.completed message 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.

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

Errors every call can return are in Errors and Authentication.