---
title: "Ceremony"
description: "The ceremony object represents a signing session where a recipient interacts with an envelope."
canonical: "https://signatureapi.com/docs/api/resources/ceremonies/object"
source: "https://signatureapi.com/docs/api/resources/ceremonies/object.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T12:10:02Z"
---

# Ceremony

The ceremony object represents a signing session where a recipient interacts with an envelope.

_Last verified against API version 1.18.0._

A ceremony is the session where a recipient authenticates and acts on an envelope. Depending on the recipient type, those actions include signing, approving, or preparing documents.

Each recipient has one active ceremony at a time. Creating a new ceremony for a recipient automatically revokes any previous ceremony.

A ceremony belongs to a [recipient](https://signatureapi.com/docs/api/resources/recipients/object).

## Lifecycle

The ceremony object has no `status` property. Read the recipient's `status` and the ceremony's `url` to tell where the ceremony is. See the [ceremony lifecycle](https://signatureapi.com/docs/api/resources/ceremonies/lifecycle) for the transitions and what each one looks like in the API.

## Attributes

#### `authentication` (array of authentication object)

**Email Link Authentication**

With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session.

#### `type` (enum)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For email link authentication, this value is `email_link`.

#### `subject_override` (string | null)

The custom subject line used for this recipient's invitation email. `null` if the envelope title is used.

#### `message_override` (string | null)

The custom message body used for this recipient's invitation email. `null` if the envelope message is used.

**Email Code Authentication**

With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony.

#### `type` (enum)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For email code authentication, this value is `email_code`.

**Custom Authentication**

With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access.

#### `type` (enum)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For custom authentication, this value is `custom`.

#### `provider` (string)

The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider.

#### `data` (object)

Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log.

> **Warning:** The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity.
>
> Review our [Terms & Conditions](https://signatureapi.com/docs/legal/terms/terms) for details.

#### `redirect_url` (string | null)

An HTTPS URL to redirect the recipient to after they complete or decline the ceremony. Embedded ceremonies ignore it.

Learn more in [Redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url).

#### `redirect_delay` (integer | null)

The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies).

Defaults to `3`. Allowed range: `0` to `20`.

Learn more in [Redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url).

#### `url_variant` (enum)

The format of the ceremony URL.

Available options:

- `standard` (default): Full-length URL. Works for most use cases.
- `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications.

#### `embeddable_in` (array of strings)

Origins allowed to embed this ceremony in an iframe.

These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the [frame-ancestors documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources).

Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`.

> **Note:** Only the origin (scheme and host) is used. Paths are ignored.

#### `url` (string | null)

The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application.

This property is `null` when:

- The first authentication method is `email_link`, even when other methods follow it. SignatureAPI delivers the URL by email in that case.
- The ceremony is not active (for example, it is completed, revoked, or declined) or the recipient is still `awaiting` their turn.

A `standard` URL is valid for 30 days, and every read of the envelope or recipient returns a new one. A `short` URL stays the same until it expires. Creating a new ceremony for the same recipient invalidates the earlier URLs. Learn more in [Ceremony URL](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url#url-expiration).

### Example: Email link

Response 200 OK:

```json
{
  "authentication": [
    {
      "type": "email_link",
      "subject_override": null,
      "message_override": null
    }
  ],
  "redirect_url": null,
  "redirect_delay": 3,
  "embeddable_in": [],
  "url_variant": "standard",
  "url": null
}
```

### Example: Email code

Response 200 OK:

```json
{
  "authentication": [
    {
      "type": "email_code"
    }
  ],
  "redirect_url": null,
  "redirect_delay": 3,
  "embeddable_in": [],
  "url_variant": "standard",
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXMiOiJzZXNfMWNoSUVrTE9tdFVNRG9hTDhwOUEifQ.c2lnbmF0dXJl"
}
```

### Example: Custom authentication

Response 200 OK:

```json
{
  "authentication": [
    {
      "type": "custom",
      "provider": "Acme Portal",
      "data": {
        "Session ID": "se_88620999344",
        "Authenticated At": "2026-11-02T14:03:11Z"
      }
    }
  ],
  "redirect_url": "https://acme.example/signing-complete",
  "redirect_delay": 5,
  "embeddable_in": [
    "https://app.acme.example"
  ],
  "url_variant": "standard",
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXMiOiJzZXNfMWNoSUVrTE9tdFVNRG9hTDhwOUEifQ.c2lnbmF0dXJl"
}
```
