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_variant": "standard",
"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 array 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 the recipient.

​
Body Parameters

​
authentication
array of authentication object
required
​
redirect_url
string

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

Learn more in Redirect URL.

​
url_variant
enum

The type of ceremony URL returned for sharing flexibility.

Available options are short and standard. The default is standard.

Use short when you need to share the URL in space-constrained channels such as SMS or push notifications.

​
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_variant": "standard",
"url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..."
}