Create a ceremony

Create a new signing ceremony for a recipient with custom authentication options.

POST /v1/recipients/{recipient_id}/ceremonies

Email Link

// 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."
    }
  ]
}

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "email_code"
    }
  ]
}

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "custom",
      "provider": "SuperApp",
      "data": {
        "Session ID": "se_88620999344",
        "Authenticated At": "2025-12-31T23:59:59Z"
      }
    }
  ],
  "embeddable_in": [
    "https://superapp.example.com"
  ]
}

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "email_link"
    }
  ],
  "redirect_url": "https://example.com/signing-complete",
  "redirect_delay": 5
}

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "custom",
      "provider": "MyApp",
      "data": {
        "user_id": "usr_12345"
      }
    }
  ],
  "embeddable_in": [
    "https://app.example.com",
    "https://staging.example.com"
  ],
  "redirect_url": "https://app.example.com/done"
}

Email Link

// HTTP Status Code 201

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

// HTTP Status Code 201

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

// HTTP Status Code 201

{
  "authentication": [
    {
      "type": "custom",
      "provider": "SuperApp",
      "data": {
        "Session ID": "se_88620999344",
        "Authenticated At": "2025-12-31T23:59:59Z"
      }
    }
  ],
  "embeddable_in": [
    "https://superapp.example.com"
  ],
  "redirect_url": null,
  "redirect_delay": 3,
  "url_variant": "standard",
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..."
}

// HTTP Status Code 201

{
  "authentication": [
    {
      "type": "email_link"
    }
  ],
  "embeddable_in": [],
  "redirect_url": "https://example.com/signing-complete",
  "redirect_delay": 5,
  "url_variant": "standard",
  "url": null
}

// HTTP Status Code 201

{
  "authentication": [
    {
      "type": "custom",
      "provider": "MyApp",
      "data": {
        "user_id": "usr_12345"
      }
    }
  ],
  "embeddable_in": [
    "https://app.example.com",
    "https://staging.example.com"
  ],
  "redirect_url": "https://app.example.com/done",
  "redirect_delay": 3,
  "url_variant": "standard",
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..."
}

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.

Email Link

// 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."
    }
  ]
}

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "email_code"
    }
  ]
}

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "custom",
      "provider": "SuperApp",
      "data": {
        "Session ID": "se_88620999344",
        "Authenticated At": "2025-12-31T23:59:59Z"
      }
    }
  ],
  "embeddable_in": [
    "https://superapp.example.com"
  ]
}

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "email_link"
    }
  ],
  "redirect_url": "https://example.com/signing-complete",
  "redirect_delay": 5
}

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "custom",
      "provider": "MyApp",
      "data": {
        "user_id": "usr_12345"
      }
    }
  ],
  "embeddable_in": [
    "https://app.example.com",
    "https://staging.example.com"
  ],
  "redirect_url": "https://app.example.com/done"
}

Email Link

// HTTP Status Code 201

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

// HTTP Status Code 201

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

// HTTP Status Code 201

{
  "authentication": [
    {
      "type": "custom",
      "provider": "SuperApp",
      "data": {
        "Session ID": "se_88620999344",
        "Authenticated At": "2025-12-31T23:59:59Z"
      }
    }
  ],
  "embeddable_in": [
    "https://superapp.example.com"
  ],
  "redirect_url": null,
  "redirect_delay": 3,
  "url_variant": "standard",
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..."
}

// HTTP Status Code 201

{
  "authentication": [
    {
      "type": "email_link"
    }
  ],
  "embeddable_in": [],
  "redirect_url": "https://example.com/signing-complete",
  "redirect_delay": 5,
  "url_variant": "standard",
  "url": null
}

// HTTP Status Code 201

{
  "authentication": [
    {
      "type": "custom",
      "provider": "MyApp",
      "data": {
        "user_id": "usr_12345"
      }
    }
  ],
  "embeddable_in": [
    "https://app.example.com",
    "https://staging.example.com"
  ],
  "redirect_url": "https://app.example.com/done",
  "redirect_delay": 3,
  "url_variant": "standard",
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..."
}