SealDrop Book a demo

Send a request when a deal or file opens

Developers · Guides

For: Broker, law and immigration CRMs. When a deal, case or file opens in your system, it sends the person SealDrop's secure link — with the organization's own wording, branding and questionnaire — exactly once, even if your call is retried.

Before you start

  • A key with the Send and pull access (requests:write, forms:read and the pull scopes), made by an admin in Settings → Developers. Start with a test key: its emails go only to the admin who made it.
  • The questionnaire to send, made in SealDrop (Questionnaires). GET /v1/questionnaires lists them with their ids.

The steps

  1. Send: POST /v1/requests with the person's name and email (or mobile, when texts are on the plan), an optional note and questionnaireId.
  2. Use an Idempotency-Key — your record's id is ideal. If the call times out and you retry with the same key and body, you get the first answer back instead of a second email (remembered 24 hours).
  3. Keep the request's id on your record: events, webhooks and the pull guide all name it.

The code

Complete, in your language. Put your key in SEALDROP_API_KEY; replace the lines marked your code with your own. These exact samples run against the API in SealDrop's tests.

curl -X POST https://api.sealdrop.ca/v1/requests \
  -H "Authorization: Bearer $SEALDROP_API_KEY" \
  -H "Idempotency-Key: deal-48213" \
  -H "Content-Type: application/json" \
  -d '{
    "person": { "name": "Amara Okafor", "email": "amara.okafor@example.com" },
    "note": "Please upload your last two pay stubs and a photo ID."
  }'
const API = 'https://api.sealdrop.ca';
const headers = { Authorization: `Bearer ${process.env.SEALDROP_API_KEY}`, 'Content-Type': 'application/json' };

// Once, at start-up: the questionnaire to send with each new deal (made in SealDrop).
const { questionnaires } = await (await fetch(`${API}/v1/questionnaires`, { headers })).json();
const intake = questionnaires.find((q) => q.name === 'Mortgage intake');

// Whenever a deal opens in your CRM:
async function onDealOpened(deal) {
  const res = await fetch(`${API}/v1/requests`, {
    method: 'POST',
    // The deal's id: if this call times out and you retry, the person still gets one email.
    headers: { ...headers, 'Idempotency-Key': `deal-${deal.id}` },
    body: JSON.stringify({
      person: { name: deal.clientName, email: deal.clientEmail },
      note: 'Please upload your last two pay stubs and a photo ID.',
      ...(intake ? { questionnaireId: intake.id } : {}),
    }),
  });
  if (!res.ok) throw new Error((await res.json()).error.code);
  const { request } = await res.json();
  return request.id; // keep it on the deal: webhooks and events name it
}

await onDealOpened({ id: 48213, clientName: 'Amara Okafor', clientEmail: 'amara.okafor@example.com' });
import os, requests

API = "https://api.sealdrop.ca"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['SEALDROP_API_KEY']}"

# Once, at start-up: the questionnaire to send with each new deal (made in SealDrop).
questionnaires = s.get(f"{API}/v1/questionnaires", timeout=30).json()["questionnaires"]
intake = next((q for q in questionnaires if q["name"] == "Mortgage intake"), None)

def on_deal_opened(deal):
    body = {
        "person": {"name": deal["client_name"], "email": deal["client_email"]},
        "note": "Please upload your last two pay stubs and a photo ID.",
    }
    if intake:
        body["questionnaireId"] = intake["id"]
    # The deal's id: if this call times out and you retry, the person still gets one email.
    res = s.post(f"{API}/v1/requests", json=body, headers={"Idempotency-Key": f"deal-{deal['id']}"}, timeout=30)
    res.raise_for_status()
    return res.json()["request"]["id"]  # keep it on the deal: webhooks and events name it

on_deal_opened({"id": 48213, "client_name": "Amara Okafor", "client_email": "amara.okafor@example.com"})

Knowing when it's back

Have an admin add a webhook for request.received: you'll get the request's id within seconds of the person submitting. Then follow the pull guide. Other events: request.sent, request.expired, request.cancelled, request.email_bounced.

Good to know

  • The request goes out exactly as from the app — the organization's wording, branding, link lifetime and limits. In the inbox it is marked Sent by API with the key's name.
  • Its email subject ends with a short code — the first 6 characters of the request's reference (e.g. · Ref 7A3F2C) — so each request is its own conversation in the person's inbox; a resend's subject starts New link:. An admin can turn the code off.
  • The answer says what happened on each channel (delivery). Later: /resend, /cancel or /filed on the request.
  • One person at a time. For a whole group (a season, a renewal), see group sends.

Try it safely

A test key works the same way, but the email goes only to the admin who made the key (subject starting [Test]) and texts are never sent. Up to 100 test requests a day; they're deleted after 7 days.

← The API guide · Reference · Changelog