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_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "email_link",
      "subject_override": "Please sign the Service Agreement",
      "message_override": "Please review and sign the attached agreement."
    }
  ]
}

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

// 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
}