Ceremony URL

Recipients use the ceremony URL to access their signing ceremony and complete their actions.

By default, SignatureAPI creates a ceremony for each recipient when you create an envelope. It uses email link authentication and sends the recipient an email with their ceremony link. You don’t need to handle URL delivery in that case.

You may want to obtain the ceremony URL directly to:

• Embed the signing ceremony in your web or mobile application
• Redirect users to the ceremony from within your application workflow
• Send the invitation through your own email infrastructure with custom branding

When ceremony URLs are available

A ceremony URL is available when the ceremony is active and not yet completed. If the first authentication method is email_link, SignatureAPI delivers the URL by email. The url property will be null in that case.

How to get a ceremony URL

Set the ceremony’s authentication method to one of the following:

• Email Code
• Custom Authentication
• Multiple Authentication with Email Code or Custom Authentication as the first step

The URL is returned in the url property of the ceremony object. You can retrieve it in several ways.

From envelope operations

When you create or retrieve an envelope, the ceremony URL is available in the url property of each recipient’s ceremony object.

{
  "id": "abcdef12-3456-7890-1234-abcdef123456",
  "title": "Service Agreement",
  "recipients": [
    {
      "type": "signer",
      "key": "client",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "ceremony": {
        "authentication": [
          {
            "type": "email_code"
          }
        ],
        "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR...",
        //...
      }
      //...
    }
  ]
  //...
}

From recipient operations

When you retrieve a recipient, the ceremony URL is available in the url property of the recipient’s ceremony object.

{
  "type": "signer",
  "key": "client",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "ceremony": {
    "authentication": [
      {
        "type": "email_code"
      }
    ],
    "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR...",
    //...
  }
  //...
}

From ceremony operations

When you create a ceremony using the Create Ceremony endpoint, the URL is returned in the url property of the ceremony object.

{
  "authentication": [
    {
      "type": "email_code"
    }
  ],
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR...",
  //...
}

Short ceremony URLs

Standard ceremony URLs are long. They may not fit in space-constrained channels like SMS or push notifications.

Set url_variant to short when creating the ceremony to generate a shorter URL.

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "custom",
      "provider": "SuperApp",
      "data": {
        "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
        "Authenticated At": "2025-12-31T23:59:59Z"
      }
    }
  ],
  "url_variant": "short"
}

// HTTP/1.1 201 Created
{
  //...
  "url": "https://sign.signatureapi.com/s/BgnexxxxxxxxIbRi"
}

URL expiration

Ceremony URLs expire 30 days after creation, or when a new ceremony is created for the same recipient. Contact support to adjust the expiration period.

How to get a new URL depends on the authentication method and URL variant:

Invalid or expired links

Recipients may see an “Invalid link” error when accessing a ceremony URL. Common causes:

• The URL expired. Ceremony URLs expire 30 days after creation. Create a new ceremony to generate a fresh URL.
• A newer ceremony replaced it. Creating a new ceremony for the same recipient invalidates the previous URL. Only the most recent ceremony URL is active.
• The envelope was canceled or completed. Ceremony URLs stop working after the envelope reaches a terminal status.
• The URL was modified. The full URL, including the token, must be used exactly as returned by the API. Truncated or modified URLs will not work.

If a recipient reports an invalid link, check the envelope and recipient status first. If the envelope is still in progress, create a new ceremony to generate a new URL.