SealDrop Book a demo

Pull received documents into a client file

Developers · Guides

For: Records and practice-management software. When someone submits, your system downloads their documents and answers into the right file and confirms the import; SealDrop then deletes its copy, so the documents live in one place: your system.

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.received and request.file_scanned and run the same code when one arrives.

The steps

  1. Find what arrived: GET /v1/requests?status=received — requests the person submitted, not yet imported.
  2. Read one: GET /v1/requests/{id} — who it's from, the note and reply, and its files with their malware-scan status. A file is pending for a minute or two after upload: come back later.
  3. Download each clean file: GET /v1/files/{id}/download gives a link that works for 5 minutes; fetch it without the Authorization header. A file that failed the scan is never served.
  4. The answers as data, when the request had a questionnaire: GET /v1/requests/{id}/answers (the answers PDF is also one of the files).
  5. 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.

← The API guide · Reference · Changelog