canonical: https://jentic.com/apis/confluence.dimagi.com/commcare

# Confluence Dimagi CommCare HQ API

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.

## For AI 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.

## Scope

Does not handle clinical billing, EHR record exchange (HL7/FHIR), or patient-facing portals - use for CommCare project data access only.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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 your Jentic One instance. 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.

Example prompt: 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

| 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) |

## Key resources

- **Cases** — Read individual cases, create/update via CaseXML, and bulk-fetch by ID
- **Forms** — List form submissions, retrieve a single submission, and download attachments
- **Users** — List mobile workers and fetch a single mobile worker by ID
- **Web users** — List web users and read web user details
- **Applications** — List CommCare apps in a project and fetch a single application
- **Lookups** — List and read lookup tables (fixtures) used by mobile applications
- **Messaging** — List SMS messages and fetch a single SMS by message ID

## Why Jentic

- **Setup:** Wiring the CommCare HQ API by hand means learning its API key or basic auth, threading the project domain through every path, and handling case, form, and receiver calls yourself. Through Jentic you install once, import the CommCare HQ API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** CommCare puts the project domain and case id in the URL path (/a/{domain}/api/v0.5/case/{caseId}), so a rule can pin your agent to one project domain or case. You choose the operations it may call, so you can allow case and form reads while leaving case creation or the receiver submission out unless you add them.
- **Credential handling:** Your CommCare API key or basic credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'fetch a CommCare case' or 'list project forms', and Jentic returns the matching CommCare operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **KoboToolbox API** — KoboToolbox is a humanitarian-sector data collection platform with a similar mobile-first model
- **ODK Central API** — Open Data Kit is the open-source data collection toolkit CommCare's XForm format derives from
- **SurveyMonkey API** — SurveyMonkey covers web survey distribution where CommCare focuses on offline mobile workflows

## FAQ

### 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 with Jentic One, the self-hosted execution layer.

### 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 your Jentic One instance 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.

### Can I limit what my agent is allowed to do with the CommCare HQ API?

Yes. Because you run Jentic One yourself, your own rules decide which CommCare HQ operations and credentials the agent may use. Since CommCare puts the project domain and case id in the URL path, such as /a/{domain}/api/v0.5/case/{caseId}, you can pin the agent to a single project space or case. You can also allow only read operations like GET /a/{domain}/api/v0.5/case and GET /a/{domain}/api/v0.5/form while leaving out case creation via CaseXML and form submission to the /a/{domain}/receiver endpoint.