March 6, 2026  •  OtterDocs Team

Getting Started with the OtterDocs API

The OtterDocs Document Notification API is built to be straightforward. If you can make an HTTP POST request, you can send your first SMS notification in well under 30 minutes. Here's everything you need to know.

What the API Does

The OtterDocs API accepts document notification requests from your application and delivers SMS messages to your customers' mobile numbers. You control the message content and the recipient — OtterDocs handles the carrier routing, delivery tracking, and reporting.

Common integration points include:

• Loan origination systems triggering notifications when documents are ready to sign
• CRM workflows sending follow-up notifications after a document is generated
• Custom business applications automating client communication at scale

Step 1 — Get Your API Key

Create a free OtterDocs account and navigate to your dashboard. Your API key is shown on the API Settings page. Treat it like a password — don't commit it to source code or expose it in client-side JavaScript.

Pass your key in every request as an HTTP header:

Authorization: Bearer YOUR_API_KEY

Step 2 — Send Your First Notification

The core endpoint accepts a POST request with the recipient's phone number, your message body, and an optional document URL:

POST https://api.otterdocs.com/v1/notify

{
  "to":       "+15551234567",
  "message":  "Hi {{first_name}}, your document is ready. Review it here: {{doc_url}}",
  "doc_url":  "https://yourdomain.com/docs/abc123",
  "ref_id":   "loan-8821"
}

The ref_id field is optional but recommended — it lets you correlate delivery events back to records in your own system.

Step 3 — Handle the Response

A successful request returns a 202 Accepted with a message ID you can use to poll for status:

{
  "status":     "queued",
  "message_id": "msg_7Xk2pLqR9",
  "ref_id":     "loan-8821"
}

Step 4 — Track Delivery

OtterDocs provides two ways to track delivery status:

• Poll the status endpoint: GET /v1/notify/{message_id} returns the current delivery status (queued, sent, delivered, failed).
• Webhooks (recommended): Register a callback URL in your dashboard and OtterDocs will POST delivery events to your server in real time — no polling required.

Tips for a Smooth Integration

• Always format phone numbers in E.164: +15551234567, not 555-123-4567. Malformed numbers are the most common source of delivery failures.
• Keep messages concise: SMS messages over 160 characters are split into multiple segments and billed per segment. Aim to keep notification messages under that limit.
• Use ref_id consistently: Tagging every request with your internal record ID makes debugging and reporting dramatically easier.
• Test in sandbox mode first: Your free account includes a sandbox environment where messages are validated but not actually delivered — perfect for integration testing.