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.

The values provided in data must be sufficient for verifying the recipient’s authentication. For instance, an expert witness in a legal proceeding should be able to correlate these values with the authentication details in your system.

When using custom authentication, you must retain all records necessary to prove the recipient’s authentication, such as session information. Please review our Terms & Conditions for more details.

For additional ceremony options like embeddable_in or redirect_url, see the Create Ceremony reference.

​
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.

Was this page helpful?

Ceremony objectRedirect URL