Create a ceremony – SignatureAPI Docs

Creates a new ceremony for a recipient. Any previous active ceremony for the recipient is automatically revoked.

The authentication array specifies which authentication methods the recipient must complete to access the ceremony. You can configure multiple methods. Recipients complete them in sequence. Learn more in Recipient Authentication.

Path Parameters

recipient_id

string

required

The unique identifier of the recipient. Recipient IDs use the re_ prefix.

Body Parameters

authentication

array of authentication object

required

Show 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

required

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

For email link authentication, set type to email_link.

subject_override

string

A custom subject line for the invitation email sent to this recipient. When not set, the subject defaults to the envelope title.

Maximum 500 characters.

message_override

string

A custom message body for the invitation email sent to this recipient. When not set, the message defaults to the envelope message.

Supports Markdown formatting: **bold**, *italic*, and \n\n for paragraph breaks. Maximum 2000 characters.

Show 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

required

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

For email code authentication, set type to email_code.

Show 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

required

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

For custom authentication, set type to custom.

provider

string

required

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

required

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.

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 for details.

redirect_url

string

An HTTPS URL to redirect the recipient to after the ceremony finishes.

Learn more in Redirect URL.

redirect_delay

integer

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.

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.

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

Only the origin (scheme and host) is used. Paths are ignored.

Returns

Returns a 201 Created status code with a ceremony object on success, or an error otherwise.

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies // X-API-Key: key_test_... // Content-Type: application/json { "authentication": [ { "type": "email_link", "subject_override": "Please sign the Service Agreement", "message_override": "Please review and sign the attached agreement." } ] }

// HTTP/1.1 201 Created { "authentication": [ { "type": "email_link", "subject_override": "Please sign the Service Agreement", "message_override": "Please review and sign the attached agreement." } ], "embeddable_in": [], "redirect_url": null, "redirect_delay": 3, "url_variant": "standard", "url": null }