Skip to main content
POST
/
v1
/
recipients
/
{recipient_id}
/
ceremonies
// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// 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

Before a recipient can enter the ceremony, they must complete authentication. The authentication array specifies which authentication methods are required for the recipient to access the ceremony. You can configure multiple authentication methods that the recipient must complete in sequence. For example, you might require both custom authentication and email code verification. Learn more about available authentication methods and how to configure them in the Recipient Authentication section.

​
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.Defaults to an empty list ([]), meaning the ceremony cannot be embedded unless you explicitly allow at least one origin. To allow embedding in all origins (not recommended for production), use ["*"].
To ensure compatibility, only the origin (scheme and host) is considered; paths are ignored.

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