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