Skip to main content
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.
When SignatureAPI sends the URL directly to the recipient (as with Email Link Authentication), the url property is null. You don’t need to handle delivery yourself.

​
How to get a ceremony URL

Set the ceremony’s authentication method to one of the following: 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.
Envelope 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.
Recipient 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.
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.
Request
// 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"
}
Response
// HTTP Status Code 201

{
  //...
  "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:
AuthenticationStandard URLShort URL
Email LinkResend or Create CeremonyCreate Ceremony
Email CodeGet EnvelopeCreate Ceremony
CustomGet EnvelopeCreate Ceremony
Short URLs do not refresh automatically. Create a new ceremony to generate a new short URL.