Confluence Dimagi CommCare HQ API

Name: CommCare HQ API
Brand: CommCare HQ API
Availability: InStock

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

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.

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

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 instance

Jentic 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

GET STARTED

Start building with CommCare HQ API

Explore with Jentic

View OpenAPI Document

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.

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

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

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

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.

Intent-based discovery

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.

Time to first call

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

Confluence Dimagi CommCare HQ API

Connect the CommCare HQ API to your agent

Capabilities

Start building with CommCare HQ API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs