---
title: "Embed Policy Signing in Your Portal"
description: "Create a policy application envelope for a policyholder who is already signed in to your portal, then show the signing ceremony inside your app."
canonical: "https://signatureapi.com/docs/use-cases/insurance"
source: "https://signatureapi.com/docs/use-cases/insurance.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:55Z"
---

# 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.

_Last verified against API version 1.18.0._

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](https://signatureapi.com/docs/api/resources/places/checkbox).
- **Captured answer.** `capture_as: disclosure_ack` stores the checkbox value in the envelope's `captures`. See [Captures](https://signatureapi.com/docs/api/resources/envelopes/captures).
- **`delivery_type: none`.** SignatureAPI does not email the signed documents to the policyholder. Your portal shows or stores them. See [Recipient object](https://signatureapi.com/docs/api/resources/recipients/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`](https://signatureapi.com/docs/api/resources/ceremonies/create), 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](https://signatureapi.com/docs/api/guides/how-to/custom-authentication) and the [embedded signing guide](https://signatureapi.com/docs/embedded/web-app). Create the ceremony only after the envelope is `in_progress`.

## Webhooks to listen for

- [`envelope.started`](https://signatureapi.com/docs/api/resources/events/envelope-events): the envelope is `in_progress`, so you can create the ceremony.
- [`recipient.completed`](https://signatureapi.com/docs/api/resources/events/recipient-events): 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`](https://signatureapi.com/docs/api/resources/events/deliverable-events): 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](https://signatureapi.com/docs/api/guides/how-to/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.

### Example: Default

Policy Application (sample).

```http
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"
    }
  ]
}
```

Response 201 Created:

```json
{
  "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
}
```

Response 422 Unprocessable Content:

```json
{
  "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 that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
