Send a request when a deal or file opens
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:readand 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/questionnaireslists them with their ids.
The steps
- Send:
POST /v1/requestswith the person's name and email (or mobile, when texts are on the plan), an optional note andquestionnaireId. - 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).
- Keep the request's
idon 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 startsNew link:. An admin can turn the code off. - The answer says what happened on each channel (
delivery). Later:/resend,/cancelor/filedon 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.