POST
/
v1
/
recipients
/
{recipient_id}
/
ceremony
// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremony
// X-API-Key: key_test_...
{
  "authentication": {
    "type": "custom",
    "provider": "SuperApp",
    "data": {
      "Session ID": "se_88620999344",
      "Authenticated At": "Dec 31, 2025 23:59:59"
      }
  },
  "embeddable_in": [
      "https://superapp.example.com"
  ]
}

{
  "authentication": {
    "type": "custom",
    "provider": "SuperApp",
    "data": {
      "Session ID": "se_88620999344",
      "Authenticated At": "Dec 31, 2025 23:59:59"
      }
  },
  "embeddable_in": [
      "https://superapp.example.com"
  ],
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..."
}

This operation creates a new ceremony for a recipient.

​
Ceremony Authentication

The ceremony takes an authentication property that describes how the recipient is authenticated.

With Link via Email authentication, SignatureAPI sends the recipient a link via email. The recipient can click the link to initiate the ceremony.

With Custom authentication, the API returns a URL in the response. You have to deliver this URL to the recipient, or embed it in a web or mobile application, to initiate the ceremony.

​
Path Parameters

​
recipient_id
string
required

The unique identifier of a recipient.

​
Body Parameters

​
authentication
authentication object
required

Defines how the recipient authenticates to this ceremony.

Authentication methods can be either link via email or custom.

​
redirect_url
string

A URL to redirect the recipient to after a ceremony is finished.

Learn more in Redirect URL.

​
embeddable_in
array of strings

List of sources allowed to embed this ceremony (for web embedding).

These sources will be used in the frame-ancestor directive of the ceremony’s HTTP Content Security Policy (CSP).

Sources usually take the form of a scheme and host, like https://app.example.com, but can also use wildcards, like https://*.example.com. For all available options, refer to the frame‑ancestors documentation.

To ensure compatibility, we consider only the origin (scheme and host) of the URL and exclude the path.

​
Returns

Returns a 201 Created status code along with a ceremony object after successful creation, or an error otherwise.

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremony
// X-API-Key: key_test_...
{
  "authentication": {
    "type": "custom",
    "provider": "SuperApp",
    "data": {
      "Session ID": "se_88620999344",
      "Authenticated At": "Dec 31, 2025 23:59:59"
      }
  },
  "embeddable_in": [
      "https://superapp.example.com"
  ]
}

{
  "authentication": {
    "type": "custom",
    "provider": "SuperApp",
    "data": {
      "Session ID": "se_88620999344",
      "Authenticated At": "Dec 31, 2025 23:59:59"
      }
  },
  "embeddable_in": [
      "https://superapp.example.com"
  ],
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..."
}