Confluence Dimagi CommCare HQ API
★ Only Publicly Available OpenAPI DocumentHealthcareClinical DataapiKey, basic17 EndpointsREST
For Agents
Read and write CommCare HQ cases, forms, mobile workers, and SMS history. Useful for agents that sync field data into analytics warehouses or trigger follow-up workflows from form submissions.
Use for: Get a CommCare case by case ID for follow-up triage, List all form submissions in the maternal-health project for the last 7 days, Retrieve a photo attachment captured in a CommCare form, Find all mobile workers assigned to a specific project space
Not supported: Does not handle clinical billing, EHR record exchange (HL7/FHIR), or patient-facing portals — use for CommCare project data access only.
Jentic publishes the only available OpenAPI specification for CommCare HQ API, keeping it validated and agent-ready. CommCare HQ is Dimagi's mobile data collection and case management platform used widely in global health, social services, and frontline worker programs. The API exposes 17 endpoints to read and write cases, ingest XForm submissions, list mobile and web users, fetch applications and lookup tables (fixtures), and pull SMS message history. Operations are scoped to a CommCare project space (the {domain} path parameter) and most are read-oriented, with case create/update via XML and form submission via the legacy receiver endpoint.
Install Jentic One Beta
Connect the CommCare HQ API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the CommCare HQ API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with CommCare HQ API.
Retrieve a specific case from a CommCare project space and read its case properties
Create or update a case by submitting CaseXML to the case endpoint
Bulk-fetch cases by ID list to hydrate a downstream system in one round trip
List form submissions filtered by app, xmlns, or date range for analytics ingestion
Pull form attachments such as photos, signatures, and audio captured in the field
List mobile workers and web users in a project to keep an HRIS in sync
Inspect application metadata and lookup tables to validate field configurations
Use Cases
Patterns agents use CommCare HQ API for, with concrete tasks.
★ Field Data Sync to Analytics Warehouse
Periodically pull form submissions and case data from CommCare HQ into a data warehouse for program reporting. The agent calls GET /a/{domain}/api/v0.5/form with date filters, paginates through results, and stores the JSON into BigQuery or Snowflake. Attachments such as photos can be downloaded individually via the form attachment endpoint when imagery is part of the program record. This replaces brittle one-off CSV exports with a scheduled, idempotent pull.
Call GET /a/maternal-health/api/v0.5/form with received_on filters covering the last 24 hours, page through results, and write each submission to the forms table in the warehouse.
Frontline Worker Roster Reconciliation
Keep an HR or payroll system in sync with the mobile worker roster on CommCare HQ. The agent lists workers via GET /a/{domain}/api/v0.5/user, compares the result to the HR system of record, and flags additions or terminations. This is useful for NGOs and ministries of health that need an accurate active-worker count for stipend payouts and program audits.
Fetch all mobile workers in the project space malaria-2026 via GET /a/malaria-2026/api/v0.5/user and diff the result against the HRIS roster to produce an add/terminate list.
Case Triage Automation
When a high-risk case is opened in the field, an agent fetches the case properties via GET /a/{domain}/api/v0.5/case/{caseId}, applies a triage rule, and updates case state by POSTing CaseXML back to /a/{domain}/api/v0.5/case. This shortens the loop between data entry and clinical follow-up without requiring CommCare app changes.
Fetch case 7c1f... via GET /a/{domain}/api/v0.5/case/{caseId}; if risk_score > 8, POST a CaseXML update to /a/{domain}/api/v0.5/case setting status to escalated.
AI Agent Field Data Lookup via Jentic
Surface CommCare data to an AI assistant used by program managers. The agent searches Jentic for fetch a commcare case, loads the case-by-id operation schema, and executes it with the API key isolated in the Jentic vault. The same wrapper supports listing forms, pulling attachments, and reading lookup tables, so the assistant can answer ad-hoc questions about field operations without anyone exporting CSVs.
Through Jentic, search fetch a commcare case, load the GET /a/{domain}/api/v0.5/case/{caseId} schema, and execute it for case ID 7c1f... in the maternal-health project.
Key Endpoints
17 endpoints — jentic publishes the only available openapi specification for commcare hq api, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
GET
/a/{domain}/api/v0.5/case/{caseId}
Get a specific case
POST
/a/{domain}/api/v0.5/case
Create or update a case via CaseXML
POST
/a/{domain}/api/v0.5/case/bulk-fetch
Bulk fetch cases by ID
GET
/a/{domain}/api/v0.5/form
List form submissions
GET
/a/{domain}/api/v0.5/form/{formId}/attachment/{attachmentName}
Get a form attachment
GET
/a/{domain}/api/v0.5/user
List mobile workers
POST
/a/{domain}/receiver
Submit a form (XML)
GET
/a/{domain}/api/v0.5/case/{caseId}
Get a specific case
POST
/a/{domain}/api/v0.5/case
Create or update a case via CaseXML
POST
/a/{domain}/api/v0.5/case/bulk-fetch
Bulk fetch cases by ID
GET
/a/{domain}/api/v0.5/form
List form submissions
GET
/a/{domain}/api/v0.5/form/{formId}/attachment/{attachmentName}
Get a form attachment
GET
/a/{domain}/api/v0.5/user
List mobile workers
POST
/a/{domain}/receiver
Submit a form (XML)
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
CommCare API keys (X-API-Key) and Basic auth credentials are stored encrypted in the Jentic vault. Agents call operations through scoped Jentic tokens; the raw header value never enters the agent's context.
Intent-based discovery
Agents search Jentic by intent (for example, list commcare form submissions) and Jentic returns the matching CommCare operation with its input schema, so the agent picks the right endpoint without scraping confluence docs.
Time to first call
Direct CommCare integration: 1-2 days to handle XForm payloads, project-space scoping, and pagination quirks. Through Jentic: under 1 hour — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using CommCare HQ API through Jentic.
Why is there no official OpenAPI spec for CommCare HQ API?
Dimagi does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call CommCare HQ API via structured tooling. It is validated against the live API and kept up to date. Get started at https://app.jentic.com/sign-up.
What authentication does the CommCare HQ API use?
Two schemes are supported: an API key passed in the X-API-Key header, or HTTP Basic auth with a CommCare username and password. When called through Jentic the credential is held in the Jentic vault and never enters the agent's prompt.
Can I create or update cases through the API?
Yes. POST /a/{domain}/api/v0.5/case accepts CaseXML to create or update a case in a specific project space. Form submissions can also be sent to the legacy POST /a/{domain}/receiver endpoint when you need to submit a full XForm rather than a case-only update.
How do I list every form submission in a project?
Call GET /a/{domain}/api/v0.5/form. The endpoint paginates and supports filters such as received_on date ranges, app_id, and xmlns so you can scope a sync to a specific application or time window without pulling the entire submission history.
Can I download attachments such as photos from a form?
Yes. After identifying a form via GET /a/{domain}/api/v0.5/form/{formId}, call GET /a/{domain}/api/v0.5/form/{formId}/attachment/{attachmentName} to download the binary attachment by its name as recorded on the submission.
How do I pull CommCare data through Jentic?
Run pip install jentic, then await client.search('list commcare form submissions'), load the matching operation schema, and execute it. The underlying call is GET /a/{domain}/api/v0.5/form with the project domain you select at runtime.
GET STARTED