SignatureAPI
Mint Starter Kit

Use Cases

Send Signing Links via SMS

Deliver signing links through SMS or any custom channel using inline ceremonies with short URLs

By default, SignatureAPI sends signing links to recipients via email. If you need to deliver signing links through SMS, WhatsApp, or any other channel, you can disable email delivery and configure an inline ceremony with a short URL directly on the recipient.

This example creates an envelope with:

  • A single PDF document with one signature place.
  • One recipient with delivery_type set to none (deliverables are not sent automatically).
  • An inline ceremony object with custom authentication and url_variant set to short for SMS-friendly URLs.

Create the Envelope

Set delivery_type to none on the recipient so the completed deliverable is not automatically emailed. Include a ceremony object on the recipient with custom authentication (since your application handles delivery) and set url_variant to short to generate a compact URL suitable for SMS.

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

{
  "title": "Service Agreement",
  "documents": [
    {
      "url": "https://example.com/documents/agreement.pdf",
      "places": [
        {
          "key": "customer_signature",
          "type": "signature",
          "recipient_key": "customer"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "customer",
      "name": "Alex Rivera",
      "email": "alex@example.com",
      "delivery_type": "none",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "SMS",
            "data": {
              "phone": "+1-555-867-5309"
            }
          }
        ],
        "url_variant": "short"
      }
    }
  ]
}

Key properties on the recipient:

  • delivery_type: Set to none so the completed deliverable is not automatically emailed to this recipient. Your application is responsible for distributing the deliverable.
  • ceremony: Configures the signing ceremony inline. SignatureAPI creates the ceremony automatically when the envelope starts processing.
  • ceremony.authentication: Uses custom type since your application handles delivery. The provider and data values are recorded in the audit log.
  • ceremony.url_variant: Set to short to generate a compact URL like https://sign.signatureapi.com/s/BgnexxxxxxxxIbRi, which fits within SMS character limits.

The recipient still requires an email property even when delivery_type is none. The email is used for identification and audit purposes.

Get the Ceremony URL

The response includes the short ceremony URL in recipients[].ceremony.url:

// HTTP/1.1 200 OK
{
  "id": "55072f0e-b919-4d69-89cd-e7e56af00530",
  "title": "Service Agreement",
  "recipients": [
    {
      "id": "re_7v7Sion0vqjJioYmwfZ9mf",
      "key": "customer",
      "name": "Alex Rivera",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "SMS",
            //...
          }
        ],
        "url_variant": "short",
        "url": "https://sign.signatureapi.com/s/BgnexxxxxxxxIbRi"
      },
      //...
    }
  ],
  //...
}

Take the url from the ceremony response and deliver it through your SMS provider (such as Twilio, MessageBird, or Amazon SNS).

// Example: sending via Twilio
const ceremonyUrl = response.recipients[0].ceremony.url;

await twilioClient.messages.create({
  to: "+15558675309",
  from: "+15551234567",
  body: `Please sign your Service Agreement: ${ceremonyUrl}`
});

The recipient opens the link on their device, reviews the document, and signs.

Result

When the recipient completes the ceremony, SignatureAPI updates the envelope status as usual. You can track completion through webhooks or by polling the envelope.

Try It

Try this example in Postman using your test API key to create a free, non-binding test envelope. Test envelopes won’t send emails, but you can review them in your dashboard.

Keep Learning