External API

SendMeDocs provides a RESTful API for programmatically creating document requests, checking their status, downloading submitted files, and cancelling requests. This lets you integrate document collection into your existing workflows without using the dashboard.

Quick start

1. Go to Settings > API Keys in the dashboard (owner or admin only)
2. Click Create API Key, give it a name
3. Copy the key immediately — it starts with smd_ and is shown only once
4. Make your first request:

curl -X POST https://your-instance.com/api/v1/requests \
  -H "Authorization: Bearer smd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "Jane Doe",
    "recipient_contact": "jane@example.com",
    "message": "Please upload your documents.",
    "items": [
      { "prefab": "photo_id" },
      { "name": "Tax Return", "description": "Last 2 years", "allow_multiple": true },
      { "name": "Filing Status", "type": "select", "options": ["Single", "Married Filing Jointly", "Head of Household"] }
    ]
  }'

The response includes the request id and an upload_url path that the recipient will use to upload their documents. You can also use template_id instead of (or in addition to) items — see Templates.

Human operator checklist

Complete these steps before an AI (or developer) can implement the integration. These require dashboard access or organizational decisions that can't be generated by code alone.

Before implementation

• Create an API key in the dashboard — go to Settings > API Keys (requires owner or admin role). Give the key a descriptive name (e.g. "CRM integration"). Click Create.
• Copy the key immediately — it is shown exactly once. The full key looks like smd_ followed by 64 hex characters (68 chars total). Store it in your secrets manager or .env file.
• Provide the key to your integration — set it as an environment variable (e.g. SENDMEDOCS_API_KEY) so your code can include it in the Authorization header.
• Decide which prefab item types you need — see Prefab item types below. Custom items can also be defined inline.
• Set up webhook receiving (optional) — if you want to be notified when requests are completed, set up a webhook endpoint. See docs/webhooks.md.

After implementation

• Create a test request — use the API to create a request with a test email address you control.
• Complete the upload flow — open the upload_url and upload test files to verify the end-to-end flow.
• Verify file download — use the download endpoint to confirm you can retrieve the uploaded files.
• Confirm webhook delivery (if configured) — check the webhook delivery log in the dashboard to verify events are being received.

Authentication

All API requests require an Authorization header with a Bearer token:

Authorization: Bearer smd_a1b2c3d4e5f6...

API keys are org-scoped — every request made with a key operates within that organization. Keys are created in the dashboard by owners or admins.

Key format: smd_ prefix + 32 random bytes (hex-encoded) = 68 characters total. The key is stored as a SHA-256 hash on the server. The first 12 characters (key_prefix) are shown in the dashboard for identification.

Key limits: Maximum 5 API keys per organization.

If the key is missing or invalid, the API returns:

HTTP 401
{ "error": "Missing or invalid API key. Use: Authorization: Bearer smd_..." }

Rate limits

Each API key is limited to 60 requests per minute. When exceeded:

HTTP 429
{ "error": "Rate limit exceeded. Maximum 60 requests per minute." }

The rate limit uses a sliding window. Wait briefly and retry.

Base URL

All endpoints are under /api/v1/:

https://your-instance.com/api/v1/requests              GET (list) / POST (create)
https://your-instance.com/api/v1/requests/:id           GET (detail)
https://your-instance.com/api/v1/requests/:id/files/:fileId/download  GET
https://your-instance.com/api/v1/requests/:id/cancel    POST
https://your-instance.com/api/v1/templates              GET (list) / POST (create)
https://your-instance.com/api/v1/templates/:id          GET (detail) / PATCH (update) / DELETE

See also: MCP Server for AI assistant integration.

Endpoints

List requests

GET /api/v1/requests

Returns a paginated list of document requests for your organization.

Query parameters:

Response (200):

{
  "requests": [
    {
      "id": "019471a2-b3c4-7d5e-8f6a-1234567890ab",
      "recipient_name": "Jane Doe",
      "recipient_contact": "jane@example.com",
      "status": "pending",
      "created_at": "2026-02-10T12:00:00.000Z",
      "expires_at": null,
      "completed_at": null
    }
  ],
  "total": 42
}

The total field is the count of all matching requests (ignoring limit/offset), useful for building pagination UI.

curl example:

# List all requests
curl https://your-instance.com/api/v1/requests \
  -H "Authorization: Bearer smd_your_key_here"

# Filter by status with pagination
curl "https://your-instance.com/api/v1/requests?status=pending&limit=10&offset=0" \
  -H "Authorization: Bearer smd_your_key_here"

# Search by recipient
curl "https://your-instance.com/api/v1/requests?search=jane" \
  -H "Authorization: Bearer smd_your_key_here"

Create request

POST /api/v1/requests

Creates a new document request. Sends an upload link email to the recipient automatically.

Request body:

{
  "recipient_name": "Jane Doe",
  "recipient_contact": "jane@example.com",
  "message": "Please upload your documents for loan processing.",
  "expires_at": "2026-03-10T00:00:00.000Z",
  "items": [
    { "prefab": "photo_id", "is_required": true },
    { "prefab": "proof_of_address" },
    { "name": "Tax Return", "description": "Last 2 years", "is_required": true, "allow_multiple": true },
    { "name": "Date of Birth", "type": "date" },
    { "name": "Filing Status", "type": "select", "options": ["Single", "Married Filing Jointly", "Head of Household"] }
  ]
}

Or using a template:

{
  "recipient_name": "Jane Doe",
  "recipient_contact": "jane@example.com",
  "template_id": "019471a2-b3c4-7d5e-8f6a-1234567890ab",
  "items": [
    { "name": "Client ID", "type": "hidden", "value": "CRM-12345" }
  ]
}

Body fields:

Item fields:

Each item is either a prefab (predefined document type), a custom document item, or a form field:

Response (200):

{
  "id": "019471a2-b3c4-7d5e-8f6a-1234567890ab",
  "token": "abc123def456...",
  "status": "pending",
  "upload_url": "/u/abc123def456...",
  "items": [
    {
      "id": "019471a2-...",
      "name": "Photo ID",
      "description": "Driver's license, passport, or state ID",
      "is_required": true,
      "allow_multiple": false,
      "position": 0,
      "status": "pending"
    },
    {
      "id": "019471a3-...",
      "name": "Proof of Address",
      "description": "Utility bill or bank statement (within 90 days)",
      "is_required": true,
      "allow_multiple": false,
      "position": 1,
      "status": "pending"
    },
    {
      "id": "019471a4-...",
      "name": "Tax Return",
      "description": "Last 2 years",
      "is_required": true,
      "allow_multiple": true,
      "position": 2,
      "status": "pending"
    }
  ],
  "created_at": "2026-02-10T12:00:00.000Z"
}

curl example:

curl -X POST https://your-instance.com/api/v1/requests \
  -H "Authorization: Bearer smd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "Jane Doe",
    "recipient_contact": "jane@example.com",
    "items": [
      { "prefab": "photo_id" },
      { "prefab": "proof_of_address" }
    ]
  }'

Get request detail

GET /api/v1/requests/:id

Returns the full detail of a request including items, their statuses, and any uploaded files.

Response (200):

{
  "id": "019471a2-b3c4-7d5e-8f6a-1234567890ab",
  "token": "abc123def456...",
  "recipient_name": "Jane Doe",
  "recipient_contact": "jane@example.com",
  "recipient_contact_type": "email",
  "status": "completed",
  "message": "Please upload your documents.",
  "revision_count": 0,
  "created_at": "2026-02-10T12:00:00.000Z",
  "expires_at": null,
  "completed_at": "2026-02-11T09:30:00.000Z",
  "upload_url": "/u/abc123def456...",
  "items": [
    {
      "id": "019471a2-...",
      "name": "Photo ID",
      "description": "Driver's license, passport, or state ID",
      "is_required": true,
      "allow_multiple": false,
      "position": 0,
      "status": "submitted",
      "revision_note": null,
      "files": [
        {
          "id": "019471b5-...",
          "filename": "drivers_license.jpg",
          "file_size": 2048576,
          "content_type": "image/jpeg",
          "created_at": "2026-02-11T09:25:00.000Z"
        }
      ]
    }
  ]
}

Request status values:

Item status values:

curl example:

curl https://your-instance.com/api/v1/requests/019471a2-b3c4-7d5e-8f6a-1234567890ab \
  -H "Authorization: Bearer smd_your_key_here"

Download file

GET /api/v1/requests/:id/files/:fileId/download

Returns a presigned S3 download URL for a specific file. The URL is valid for 5 minutes.

Response (200):

{
  "download_url": "https://s3.example.com/org123/req456/abcdef.jpg?X-Amz-...",
  "filename": "drivers_license.jpg"
}

The download_url is a temporary presigned URL. Download the file immediately or within the 5-minute window. Do not store the URL — request a new one when needed.

Retention: Files from completed requests are automatically deleted after the retention period (Pay as you go: 7 days, $12/mo: 14 days, $25/mo and $60/mo: 30 days). Orgs can configure shorter retention in Settings. Once deleted, this endpoint returns 404. Download files promptly after request completion.

curl example:

# Get the download URL
curl https://your-instance.com/api/v1/requests/019471a2-.../files/019471b5-.../download \
  -H "Authorization: Bearer smd_your_key_here"

# Download the file using the presigned URL
curl -o drivers_license.jpg "https://s3.example.com/..."

Cancel request

POST /api/v1/requests/:id/cancel

Cancels a pending request. Only requests with status: "pending" can be cancelled. The request status is set to expired.

Response (200):

{ "success": true }

Error — not pending:

HTTP 400
{ "error": "Can only cancel pending requests" }

curl example:

curl -X POST https://your-instance.com/api/v1/requests/019471a2-.../cancel \
  -H "Authorization: Bearer smd_your_key_here"

Error responses

All errors return a JSON object with an error field:

{ "error": "Human-readable error message" }

Status codes

Prefab item types

Prefab items provide standardized names and descriptions for common document types. Use the prefab field in the items array instead of specifying name and description manually.

When using a prefab, is_required can still be overridden (defaults to true). The allow_multiple and name/description fields come from the prefab definition.

Form field types

In addition to document uploads, items can be form fields that recipients answer inline in the upload portal. Set the type field on an item:

Notes:

• select requires an options array with 2-20 non-empty strings
• hidden requires a value string — used for org-side metadata (e.g. CRM IDs, internal reference numbers). Hidden items are auto-submitted at creation and never shown to the recipient.
• Form field answers are auto-saved as the recipient types (500ms debounce). When the request is submitted, a "Form Responses" file is generated containing all answers in both .txt and .json format.

Group labels

Items with the same group_label appear under a shared section header in the upload portal. Use this to organize related items visually:

{
  "items": [
    { "name": "Full Legal Name", "type": "text", "group_label": "Personal Information" },
    { "name": "Date of Birth", "type": "date", "group_label": "Personal Information" },
    { "prefab": "photo_id", "group_label": "Identity Documents" },
    { "prefab": "proof_of_address", "group_label": "Identity Documents" }
  ]
}

Items without a group_label appear ungrouped. Group ordering follows the item order — the header appears before the first item in each group.

Templates

Templates are reusable collections of items. System templates (built-in) cover common workflows for tax, healthcare, legal, and general use. Organizations can also create their own custom templates.

When creating a request with template_id, the template's items become the base. Any items you provide are appended after the template items (useful for adding org-specific metadata via hidden fields).

List templates

GET /api/v1/templates

Returns all templates available to your organization (system templates + your org's custom templates).

Query parameters:

Response (200):

{
  "templates": [
    {
      "id": "019471a2-...",
      "name": "Individual Tax Return (1040)",
      "description": "Standard documents for individual tax return preparation",
      "category": "tax",
      "is_system": true,
      "item_count": 12
    }
  ]
}

Get template detail

GET /api/v1/templates/:id

Returns a template with its full list of items.

Response (200):

{
  "id": "019471a2-...",
  "name": "Individual Tax Return (1040)",
  "description": "Standard documents for individual tax return preparation",
  "category": "tax",
  "is_system": true,
  "item_count": 12,
  "items": [
    {
      "id": "019471a3-...",
      "name": "W-2 Forms",
      "description": "From all employers",
      "type": "document",
      "options": null,
      "is_required": true,
      "allow_multiple": true,
      "position": 0,
      "group_label": "Income Documents",
      "value": null
    }
  ]
}

Create template

POST /api/v1/templates

Creates a custom template for your organization.

Request body:

{
  "name": "New Client Onboarding",
  "description": "Documents needed for new client setup",
  "category": "general",
  "items": [
    { "name": "Photo ID", "type": "document", "is_required": true },
    { "name": "Date of Birth", "type": "date", "group_label": "Personal Info" },
    { "name": "Preferred Contact Method", "type": "select", "options": ["Email", "Phone", "Text"] }
  ]
}

Response (200):

{ "id": "019471a2-..." }

Update template

PATCH /api/v1/templates/:id

Updates a custom template's metadata. System templates cannot be modified.

Response (200):

{ "success": true }

Delete template

DELETE /api/v1/templates/:id

Permanently deletes a custom template and its items. System templates cannot be deleted.

Response (200):

{ "success": true }

AI integration guide

This section is optimized for AI-assisted development (LLM agents, copilots, code generators).

Implementation checklist — API client

1. Store the API key securely — read from environment variable (e.g. SENDMEDOCS_API_KEY), never hardcode
2. Set headers on every request: Authorization: Bearer smd_... and Content-Type: application/json
3. Create a request via POST /api/v1/requests with recipient info and items
4. Handle the response — store the id for later lookups and file downloads
5. Poll or use webhooks to know when the request is completed (see docs/webhooks.md for webhook setup)
6. Fetch request detail via GET /api/v1/requests/:id to get item statuses and file metadata
7. Download files via GET /api/v1/requests/:id/files/:fileId/download — use the presigned URL within 5 minutes
8. Handle errors — check for error field in all non-200 responses
9. Respect rate limits — implement backoff on 429 responses

Inputs your integration needs from the human/system

TypeScript types

Use these types when generating an API client:

// ============================================================================
// Query params — GET /api/v1/requests
// ============================================================================

interface ListRequestsParams {
  status?: "pending" | "completed" | "expired"
  search?: string               // partial match on name/email
  limit?: number                // 1-100, default 20
  offset?: number               // default 0
}

// ============================================================================
// Response — GET /api/v1/requests
// ============================================================================

interface ListRequestsResponse {
  requests: ListRequestItem[]
  total: number                  // total matching (ignoring limit/offset)
}

interface ListRequestItem {
  id: string
  recipient_name: string
  recipient_contact: string
  status: "pending" | "completed" | "expired"
  created_at: string             // ISO 8601
  expires_at: string | null
  completed_at: string | null
}

// ============================================================================
// Request body — POST /api/v1/requests
// ============================================================================

interface CreateRequestBody {
  recipient_name: string       // 1-255 chars, required
  recipient_contact: string    // 1-255 chars, required — email or US phone number
  message?: string             // max 1000 chars
  expires_at?: string          // ISO 8601 datetime
  locale?: "en" | "es" | "fr" | "de" | "pt" | "zh" | "ja" | "ko"  // upload portal + email language
  template_id?: string         // UUID — use template items as base
  items?: CreateRequestItem[]  // 1-200 items, required if no template_id
}

interface CreateRequestItem {
  prefab?: "photo_id" | "proof_of_address" | "proof_of_income" | "w9"
  name?: string                // max 255 chars, ignored if prefab is set
  description?: string         // max 1000 chars, ignored if prefab is set
  type?: "document" | "text" | "date" | "select" | "yes_no" | "hidden"  // default: "document"
  options?: string[]           // required for "select" type (2-20 items)
  value?: string               // required for "hidden" type (max 2000 chars)
  is_required?: boolean        // default: true
  allow_multiple?: boolean     // default: false, document type only
  group_label?: string         // visual grouping in upload portal
}

// ============================================================================
// Response — POST /api/v1/requests
// ============================================================================

interface CreateRequestResponse {
  id: string                   // UUID v7
  token: string                // upload token
  status: "pending"
  upload_url: string           // "/u/{token}"
  items: RequestItemSummary[]
  created_at: string           // ISO 8601
}

interface RequestItemSummary {
  id: string
  name: string
  description: string | null
  type: "document" | "text" | "date" | "select" | "yes_no" | "hidden"
  is_required: boolean
  allow_multiple: boolean
  position: number
  group_label: string | null
  status: "pending"
}

// ============================================================================
// Response — GET /api/v1/requests/:id
// ============================================================================

interface GetRequestResponse {
  id: string
  token: string
  recipient_name: string
  recipient_contact: string
  recipient_contact_type: "email" | "sms"
  status: "pending" | "completed" | "expired"
  message: string | null
  revision_count: number
  created_at: string           // ISO 8601
  expires_at: string | null    // ISO 8601
  completed_at: string | null  // ISO 8601
  upload_url: string           // "/u/{token}"
  items: RequestItemDetail[]
}

interface RequestItemDetail {
  id: string
  name: string
  description: string | null
  type: "document" | "text" | "date" | "select" | "yes_no" | "hidden"
  is_required: boolean
  allow_multiple: boolean
  position: number
  group_label: string | null
  status: "pending" | "submitted" | "approved" | "rejected"
  revision_note: string | null
  draft_value: string | null   // form field answer (null for document items)
  files: FileDetail[]
}

interface FileDetail {
  id: string
  filename: string
  file_size: number            // bytes
  content_type: string         // MIME type
  created_at: string           // ISO 8601
}

// ============================================================================
// Response — GET /api/v1/requests/:id/files/:fileId/download
// ============================================================================

interface DownloadResponse {
  download_url: string         // presigned S3 URL, valid for 5 minutes
  filename: string
}

// ============================================================================
// Response — POST /api/v1/requests/:id/cancel
// ============================================================================

interface CancelResponse {
  success: true
}

// ============================================================================
// Error response — all endpoints
// ============================================================================

interface ErrorResponse {
  error: string
}

Common mistakes to avoid

• Don't hardcode the API key — read it from an environment variable or secrets manager.
• Don't store presigned download URLs — they expire after 5 minutes. Always request a fresh URL when you need to download a file.
• Don't poll aggressively — if checking request status, poll no more than once per minute. Better yet, use webhooks for real-time notifications.
• Don't ignore is_required defaults — items default to is_required: true. Set is_required: false explicitly if the item is optional.
• Don't send both prefab and name — if prefab is set, the name and description fields are ignored. Use one approach or the other.
• Don't retry on 401 — an invalid API key will never become valid. Check your key configuration.
• Don't assume file order — use the position field on items to determine display order, and the request_item_id relationship to associate files with items.

Example integration flow

A typical integration creates a request, listens for completion via webhook, then downloads the files:

1. Your system  ──POST /api/v1/requests──>  SendMeDocs
                <── 200 { id, upload_url } ──

2. SendMeDocs sends upload link email to recipient
3. Recipient uploads documents via upload portal

4. SendMeDocs ──POST webhook──> Your endpoint
               { type: "request.completed", data: { id, items } }

5. Your system ──GET /api/v1/requests/:id──> SendMeDocs
               <── 200 { items: [{ files: [...] }] } ──

6. Your system ──GET /api/v1/requests/:id/files/:fileId/download──> SendMeDocs
               <── 200 { download_url } ──

7. Your system ──GET download_url──> S3
               <── file bytes ──

Without webhooks (polling approach):

1. Create the request (POST /api/v1/requests)
2. Store the request id
3. Periodically GET /api/v1/requests/:id
4. When status changes to "completed", download files
5. When status changes to "expired", handle expiration

See docs/webhooks.md for webhook setup, signature verification, and event types.

Full working example (Node.js)

const API_KEY = process.env.SENDMEDOCS_API_KEY;
const BASE_URL = process.env.SENDMEDOCS_URL; // e.g. "https://sendmedocs.com"

async function createRequest(recipient) {
  const res = await fetch(`${BASE_URL}/api/v1/requests`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipient_name: recipient.name,
      recipient_contact: recipient.email,
      message: "Please upload the required documents.",
      items: [
        { prefab: "photo_id" },
        { prefab: "proof_of_address" },
        {
          name: "Signed Agreement",
          description: "The signed service agreement we sent you",
          is_required: true,
        },
      ],
    }),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`Create request failed: ${err.error}`);
  }

  return res.json(); // { id, token, status, upload_url, items, created_at }
}

async function getRequest(requestId) {
  const res = await fetch(`${BASE_URL}/api/v1/requests/${requestId}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`Get request failed: ${err.error}`);
  }

  return res.json();
}

async function downloadFile(requestId, fileId) {
  const res = await fetch(
    `${BASE_URL}/api/v1/requests/${requestId}/files/${fileId}/download`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`Download failed: ${err.error}`);
  }

  const { download_url, filename } = await res.json();

  // Download the actual file from the presigned URL
  const fileRes = await fetch(download_url);
  const buffer = await fileRes.arrayBuffer();

  return { filename, buffer };
}

async function cancelRequest(requestId) {
  const res = await fetch(`${BASE_URL}/api/v1/requests/${requestId}/cancel`, {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}` },
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`Cancel failed: ${err.error}`);
  }

  return res.json(); // { success: true }
}

MCP server

SendMeDocs also provides an MCP server for AI assistants like Claude Desktop and Cursor. It uses the same API key authentication. See the MCP docs for setup instructions.