Docassemble API Integration: Best Practices for Developers

Introduction

Docassemble is already great at what legal aid teams need most: guided interviews that turn messy client inputs into clean, consistent documents (PDF/DOCX/RTF). But the moment you want to reduce staff re-entry, sync case data, validate information, or trigger downstream actions, you’re in integration territory—and that’s where the docassemble API becomes the difference between “a nice interview” and a truly operational workflow.

For global legal aid organizations, integrations often look like:

• pulling applicant details from an intake portal or CRM
  
• creating/updating matters in a case management system (e.g., LegalServer-style systems)
  
• validating addresses, IDs, or eligibility rules
  
• generating a document and pushing it back into the case file automatically
  

This guide is written for developers (and tech leads at legal aid orgs) implementing docassemble API integrations safely—so your interview stays fast, reliable, and maintainable over time.

1) Start with the right integration pattern (push, pull, or hybrid)

Most successful docassemble api projects use one of these patterns:

A) Pull: Docassemble calls external APIs during the interview

Use this when the interview needs data in real time (e.g., eligibility rules, case lookup, court locations).

Best practice: don’t block every user on slow third-party responses—use caching, timeouts, and graceful fallback messaging.

B) Push: External systems call Docassemble to start or prefill an interview

Use this when your CRM/case system is the “source of truth” and Docassemble should start with known data.

Best practice: prefill only what you’re confident is accurate; still ask the user to confirm critical fields.

C) Hybrid: Prefill + verify + write back

This is the most common for legal document assembly software used by legal aid:

1. pull client/case data in
   
2. ask missing questions
   
3. generate documents
   
4. push documents + structured data back to the case system

2) Treat authentication like a product feature, not a dev checkbox

Docassemble’s HTTP API requires authentication using an API key.
That single fact should drive these best practices:

• Store API keys in environment/config (never hardcode in YAML).
  
• Rotate keys on a schedule.
  
• Use separate keys per environment (dev/staging/prod).
  
• Restrict who can access admin/API settings.
  

If your legal aid org is dealing with sensitive data, treat integration credentials with the same care as your case management credentials.

3) Keep the interview fast: timeouts, retries, and “good enough” fallbacks

Integrations fail. Banks go down. CRMs rate-limit. Networks blip. Your interview shouldn’t collapse.

Do this:

• Set short timeouts for API calls (e.g., 5–10 seconds).
  
• Retry only when it’s safe (idempotent reads are safer than writes).
  
• If an external system fails, show a human message like:
  “We couldn’t fetch your case details right now. You can continue and we’ll sync later.”
  

Docassemble experts also recommend reliability patterns (retries, clear error messages, safe fallbacks) so workflows don’t break when external systems fail.

4) Use “input → validate → confirm” for anything that affects eligibility

In legal aid, one wrong value can mean:

• wrong jurisdiction
  
• wrong court form
  
• missed eligibility
  
• a document that can’t be filed
  

So even if you prefill, you should still validate:

• names (format and completeness)
  
• address (basic structure)
  
• date of birth (valid date)
  
• income fields (numeric constraints)
  
• jurisdiction/court selection (controlled lists, not free text)
  

This is where Docassemble shines compared to traditional docassembly approaches: you can combine logic + validation + document output in one guided flow. 

5) Design for audit: log what you sent and what you received

Legal aid operations often need to explain:

• why a client was eligible/ineligible
  
• what was generated
  
• when it was synced
  
• what data was used
  

Best practice:

• Log outbound requests (without storing sensitive payloads in plain text).
  
• Store response IDs and timestamps.
  
• Store a “sync status” variable (queued/sent/failed/retry).
  
• Keep generated document filenames predictable and traceable.
  

6) Use a clean separation: YAML for flow, Python for integrations

A maintainable docassemble app keeps:

• YAML focused on interview flow and logic
  
• Python modules focused on API clients and utilities
  

Why this matters:

• easier testing
  
• easier key management
  
• easier future upgrades
  

Docassemble’s development approach supports packaging and version control workflows (GitHub-based packages are common). 

Technical code section: simple patterns you can reuse

A) Calling an external REST API from Docassemble (Python helper)

import requests

def fetch_case(case_id: str, base_url: str, token: str) -> dict:
    headers = {"Authorization": f"Bearer {token}"}
    r = requests.get(
        f"{base_url}/cases/{case_id}",
        headers=headers,
        timeout=10
    )
    r.raise_for_status()
    return r.json()

B) Calling the docassemble API from another service (start/prefill workflow)

Docassemble provides an HTTP API controlled via API key authentication.

import requests

DA_BASE = "https://YOUR_DOCASSEMBLE_SERVER"
DA_API_KEY = "YOUR_API_KEY"

def da_headers():
    return {"X-API-Key": DA_API_KEY}

def start_interview(interview_name: str, initial_vars: dict):
    payload = {
        "i": interview_name,   # interview file/package reference
        "variables": initial_vars
    }
    r = requests.post(
        f"{DA_BASE}/api/session",
        json=payload,
        headers=da_headers(),
        timeout=10
    )
    r.raise_for_status()
    return r.json()

FAQ 

1) What is the docassemble API used for?

It’s used to control parts of Docassemble through HTTP—such as starting sessions/interviews, passing data in, and enabling integrations with other systems using authenticated requests.

2) Should Docassemble call the CRM, or should the CRM call Docassemble?

If the interview needs CRM data during the flow, Docassemble “pulls.” If your CRM initiates the workflow and wants prefilled interviews, the CRM “pushes.” Many legal aid teams use a hybrid model.

3) How do we keep interviews fast if third-party APIs are slow?

Use timeouts, cache where possible, and design a fallback path so users can continue. Avoid making every user wait on external systems for non-critical data.

4) What’s the safest way to handle failures?

Treat external calls as unreliable: log attempts, retry safely, and show clear user messages. Reliability patterns are key to preventing broken workflows.

5) Can we integrate Docassemble with case management tools like LegalServer-style systems?

Yes—legal aid orgs commonly integrate Docassemble with CRMs and case management tools using API-based patterns to sync intake, documents, and case updates.

6) What’s the biggest mistake developers make with Docassemble integrations?

Hardcoding credentials and building “happy-path-only” integrations. The best systems plan for retries, audit logs, validation, and human-friendly failure states from day one.