SMS Delivery via API

📘

Availability

SMS delivery is available only to workspaces that are eligible for SMS and have it enabled. Requests that set an SMS delivery method for a non-eligible workspace fail validation with a 422.

Sending a document via SMS

Set delivery_method on each recipient of Create Document or Create Document from Template:

{
  "name": "NDA",
  "files": [{ "file_url": "https://example.com/nda.pdf", "name": "nda.pdf" }],
  "recipients": [
    {
      "id": "1",
      "name": "Jane Doe",
      "email": "[email protected]",
      "delivery_method": "email_and_sms",
      "phone_number": "+14155551234"
    },
    {
      "id": "2",
      "name": "John Roe",
      "delivery_method": "sms",
      "phone_number": "+14155555678"
    }
  ]
}

Phone number rules

• phone_number must be E.164 format (for example +14155551234).
• Only country codes currently enabled for SMS are accepted. SMS is currently available for US and Canada phone numbers (+1); UK (+44) and Australia (+61) support is coming soon.
• Two SMS-only recipients on the same document cannot share the same phone number.

What SMS recipients receive

SMS content always uses fixed system templates; there is no custom SMS body. subject and message (document-level or per-recipient) apply to email notifications only. Recipients get an SMS for three moments: the signature request (invite), reminders, and document completion.

Reminders

Send Reminder and automatic reminders follow each recipient's own delivery method: email-only recipients get a reminder email, SMS-only recipients get a reminder text, and email_and_sms recipients get both. No extra parameters are needed.

Embedded signing

With embedded_signing: true, notifications are off by default. send_sms: true sends the SMS notification anyway, and send_sms_delay (0-60 minutes) delays it, skipping the send if the document is completed before the delay elapses. These mirror send_email / send_email_delay and only apply when the recipient's delivery method includes SMS.

Tracking delivery

Get Document returns delivery_method for every recipient, and recipients whose delivery includes SMS carry a nested sms object:

{
  "id": "2",
  "name": "John Roe",
  "delivery_method": "sms",
  "sms": {
    "phone_number_masked": "+1 ******5678",
    "send_sms": false,
    "send_sms_delay": 0,
    "delivery_status": "sent",
    "message_type": "invite",
    "failed": false,
    "failed_details": null
  }
}

• phone_number_masked: dialing code + last four digits; the full number is never returned.
• delivery_status: queued, sent, failed, or suppressed, for the latest SMS.
• message_type: invite, reminder, or completed.
• failed / failed_details: null until an SMS is dispatched, then the outcome of the latest attempt.

Two webhook events report SMS outcomes: document_sms_failed (terminal delivery failure) and document_sms_opted_out (number newly added to the suppression list). Both identify the affected recipient in event.related_recipient. See Events and Event Data.

Credits

Each SMS sent consumes the workspace's SMS balance. If the balance runs out, only the SMS leg is skipped and the sender is notified once; email legs (for email_and_sms recipients) still go out.

Suppression and opt-out

When a recipient opts out, their number is added to the workspace suppression list and skipped on future sends (delivery_status: suppressed). Recipients in the US and Canada opt out by replying STOP to any SignWell SMS. When UK and Australia support launches, recipients there will opt out through a link included in the SMS instead.

Test mode

Documents created with test_mode: true never send real SMS and never consume credits. To preview what the SMS-only flow does, set send_sms_test_preview_email: true on Create Document: the document owner receives a test-mode preview email (with the masked phone number) instead of the regular SMS sender-copy email.

Constraints at a glance

• Workspace must be eligible for SMS and have it enabled.
• E.164 phone numbers from enabled country codes only (currently US and Canada; UK and Australia coming soon).
• Fixed SMS templates; subject / message are email-only.
• Update Recipients does not accept SMS fields; delivery settings are set at creation.
• Suppressed (opted-out) numbers are skipped automatically.