Pull received documents into a client file
Before you start
- A key with the Pull documents access (
requests:read,files:read,answers:read), made by an admin in Settings → Developers. Start with a test key. - How you'll hear about new uploads: check every few minutes (below), or have an admin add a webhook for
request.receivedandrequest.file_scannedand run the same code when one arrives.
The steps
- Find what arrived:
GET /v1/requests?status=received— requests the person submitted, not yet imported. - Read one:
GET /v1/requests/{id}— who it's from, the note and reply, and its files with their malware-scan status. A file ispendingfor a minute or two after upload: come back later. - Download each clean file:
GET /v1/files/{id}/downloadgives a link that works for 5 minutes; fetch it without the Authorization header. A file that failed the scan is never served. - The answers as data, when the request had a questionnaire:
GET /v1/requests/{id}/answers(the answers PDF is also one of the files). - Confirm the import:
POST /v1/requests/{id}/imported. It is refused (409 not_downloaded) until every clean file was downloaded, so nothing is deleted that you didn't fetch.
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.
# 1. What arrived: requests the person submitted, not yet imported
curl "https://api.sealdrop.ca/v1/requests?status=received" \
-H "Authorization: Bearer $SEALDROP_API_KEY"
# 2. One request: who it's from, the note and reply, its files and their scan status
curl https://api.sealdrop.ca/v1/requests/$REQUEST_ID \
-H "Authorization: Bearer $SEALDROP_API_KEY"
# 3. For each clean file: a 5-minute link (fetch "url" without the Authorization header)
curl https://api.sealdrop.ca/v1/files/$FILE_ID/download \
-H "Authorization: Bearer $SEALDROP_API_KEY"
# 4. The questionnaire answers as data (when the request had one)
curl https://api.sealdrop.ca/v1/requests/$REQUEST_ID/answers \
-H "Authorization: Bearer $SEALDROP_API_KEY"
# 5. It's all in your system: SealDrop deletes its copy
curl -X POST https://api.sealdrop.ca/v1/requests/$REQUEST_ID/imported \
-H "Authorization: Bearer $SEALDROP_API_KEY"const API = 'https://api.sealdrop.ca';
const headers = { Authorization: `Bearer ${process.env.SEALDROP_API_KEY}` };
const get = async (path) => {
const res = await fetch(API + path, { headers });
if (!res.ok) throw new Error((await res.json()).error.code);
return res.json();
};
const { requests } = await get('/v1/requests?status=received');
for (const r of requests) {
const detail = await get(`/v1/requests/${r.id}`);
if (detail.files.some((f) => f.scan === 'pending')) continue; // try again in a minute
for (const f of detail.files.filter((f) => f.scan === 'clean' && !f.deleted)) {
const { url } = await get(`/v1/files/${f.id}/download`);
const bytes = Buffer.from(await (await fetch(url)).arrayBuffer());
await saveToYourSystem(r, f.name, bytes); // your code
}
if (detail.questionnaire) await saveAnswers(r, await get(`/v1/requests/${r.id}/answers`)); // your code
const done = await fetch(`${API}/v1/requests/${r.id}/imported`, { method: 'POST', headers });
if (!done.ok) throw new Error((await done.json()).error.code);
}import os, requests
API = "https://api.sealdrop.ca"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['SEALDROP_API_KEY']}"
def get(path):
res = s.get(API + path, timeout=30)
res.raise_for_status()
return res.json()
for r in get("/v1/requests?status=received")["requests"]:
detail = get(f"/v1/requests/{r['id']}")
if any(f["scan"] == "pending" for f in detail["files"]):
continue # try again in a minute
for f in detail["files"]:
if f["scan"] == "clean" and not f["deleted"]:
url = get(f"/v1/files/{f['id']}/download")["url"]
save_to_your_system(r, f["name"], requests.get(url, timeout=60).content) # your code
if detail["questionnaire"]:
save_answers(r, get(f"/v1/requests/{r['id']}/answers")) # your code
s.post(f"{API}/v1/requests/{r['id']}/imported", timeout=30).raise_for_status()Matching the right client file
Each request has the person's name, email and mobile as they were sent, and its own id. If your system starts the request (see the send guide), keep that id on your record and you'll always know where the documents go.
What SealDrop keeps
After imported, SealDrop deletes the files, answers and reply straight away — as when staff mark a request Filed. An organization can instead have its staff look first (Settings → Developers); then everything is deleted on its usual schedule. If your system downloads but never confirms, the files are still deleted on schedule (35 days at most).
Try it safely
With a test key, send yourself a test request, then POST /v1/test/requests/{id}/simulate-upload uploads SealDrop's sample PDF and photo and fills the questionnaire — through the real malware scan. Run the code above a minute later. Test requests are only visible to test keys and are deleted after 7 days.