Only use your server to communicate with our API. Do not use our API directly from your client, as API keys can be exposed. If someone gets your API key, they can access all your data in SignatureAPI.

To embed a ceremony, you need a ceremony URL. You can get a URL following these steps:

  1. Create an envelope
  2. Create a ceremony

​
Create an Envelope

Use the Create Envelope endpoint. Set ceremony_creation to manual for recipient(s) who will sign in an embedded ceremony. This stops the automatic email link from being sent.

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"
    }
  ]
}

If successful, the response will include an envelope object. Note the recipient ID in the response.

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

​
Create a Ceremony

Use the recipient ID to create a ceremony with custom authentication. Your app will authenticate the recipient instead of sending an email link.

Custom authentication needs two properties:

  • provider: Your company or app name.
  • data: Key-value pairs with authentication metadata like timestamps and session IDs.

Both provider and data values will appear in the audit logs.

When embedding in web apps, include the embeddable_in property with the list of allowed sources.

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"
    }
  },
  "embeddable_in": [
    "https://superapp.example.com"
  ]
}

If successful, the response will include the ceremony URL.

Example response:

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

Was this page helpful?

IntroductionCeremony Events