Ceremony URL

When you create an Envelope, SignatureAPI usually sends an email with a link to the signing ceremony. This link, which points to the Ceremony URL, allows recipients to access the signing ceremony and sign the document.

However, there are cases where you might want to manage the Ceremony URL yourself. For example:

• Embedding the signing ceremony in a web or mobile application.
• Redirecting recipients to the signing ceremony from your app.
• Sending the signing request email using your own email system, domain, and templates.

This guide explains how to obtain the Ceremony URL.

​

Step 1: Create an Envelope

Use the Create Envelope endpoint. Set ceremony_creation to manual for any recipient you want to handle manually. This prevents SignatureAPI from automatically sending an email with the Ceremony URL.

​

Example Request

// POST https://api.signatureapi.com/v1/envelopes HTTP/1.1
// Content-Type: application/json
// X-API-Key: key_test_...

{
  "title": "Dummy Consent",
  "documents": [
    {
      "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/five-fingers.pdf"
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "human",
      "name": "Mark Seisdedos",
      "email": "mark@example.com",
      "ceremony_creation": "manual"
    }
  ]
}

​

Example Response

If successful, the response will include an envelope object. Take note of the recipient ID in the response:

{
  //...
  "recipients": [
    {
      "id": "re_5m393QvSqy9SasSmSIG5xS",
      //...
    }
  ],
  //...
}

​

Step 2: Create a Ceremony

Use the Create Ceremony endpoint with the recipient ID to generate a Ceremony URL. If you use custom authentication, your app authenticates the recipient instead of relying on an email link sent by SignatureAPI.

Custom authentication requires two properties:

• provider: Your company or app name.
• data: Key-value pairs with authentication details, such as timestamps or session IDs.

These values will be included in the audit logs.

​

Example Request

// POST https://api.signatureapi.com/v1/recipients/re_5m393QvSqy9SasSmSIG5xS/ceremony
// X-API-Key: key_test_...
{
  "authentication": {
    "type": "custom",
    "provider": "SuperApp",
    "data": {
      "Session Id": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
      "Authenticated At": "Dec 31, 2025 23:59:59"
    }
  }
}

​

Example Response

If successful, the response will include the Ceremony URL:

{
  //...
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjI4OTE3NDYsImV4cCI6MTcyMzQ5NjU0NiwiY2VyZW1vbnlf..."
  //...
}

You can use this URL to:

• Embed the signing ceremony into your app.
• Redirect recipients to the signing ceremony from your application.
• Send the URL in an email from your system.