> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/other/commcare.md).

# Commcare

Connect CommCare to Google Sheets, BigQuery, or AI tools via Coupler.io. Export form submissions and case records without writing code.

CommCare is a mobile data collection platform used by NGOs, public health programs, and field teams to gather data via mobile forms and track cases over time. It's widely used in low-connectivity environments for community health, agriculture, and humanitarian programs.

Connecting CommCare to Coupler.io lets you move your field data into analytics tools automatically — no manual exports, no CSV uploads.

**Why connect CommCare to Coupler.io?**

* Pull form submissions and case records into Google Sheets, Excel, BigQuery, or Looker Studio for reporting
* Send field data to AI tools like ChatGPT, Claude, or Gemini for summarization or pattern detection
* Combine forms and cases using Join or Append transformations to build unified program datasets
* Set up scheduled refreshes so your dashboards always reflect the latest field activity

## Prerequisites

Before connecting, make sure you have:

* A CommCare HQ account with access to the project space you want to export
* Your CommCare **API key** (available in your CommCare HQ account settings)
* The **Project Space name** for the project you want to connect

{% hint style="info" %}
You need at least a Standard plan on CommCare HQ to access the API. The free Community plan does not include API access.
{% endhint %}

## Quick start

{% hint style="success" %}
Start with the **Cases** entity if you want a current view of people or program participants. Use **Forms** if you need the raw submission history or survey responses.
{% endhint %}

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** Log in to Coupler.io, go to the Data Flows section, and click **Add data flow**. Search for CommCare and select it as your source.
{% endstep %}

{% step %}
**Enter your CommCare credentials.** You'll be asked for your CommCare username (email), API key, and Project Space name. To find your API key, log in to CommCare HQ, go to your profile settings, and look under **API Key**.
{% endstep %}

{% step %}
**Select an entity.** Choose either **Forms** or **Cases** depending on what data you need. You can add more entities in the same data flow later.
{% endstep %}

{% step %}
**Set a start date.** Use the date picker to set the earliest date for records you want to export. Only records created or modified after this date will be included.
{% endstep %}

{% step %}
**Choose a destination.** Select where you want your data to go — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT or Claude.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** to execute your first manual sync. Check the preview to confirm your data looks correct.
{% endstep %}
{% endstepper %}

## Available entities

| Entity | Description                                                                                            |
| ------ | ------------------------------------------------------------------------------------------------------ |
| Forms  | Individual form submissions from mobile workers, including all field responses and submission metadata |
| Cases  | Tracked records for people, places, or things — with current status, properties, and history           |

## CommCare data overview

CommCare exposes two core entities through Coupler.io: **Forms** and **Cases**. Together they cover the full picture of field program activity — what was collected and who or what was tracked.

## Entities

| Entity | What it contains                                                                      |
| ------ | ------------------------------------------------------------------------------------- |
| Forms  | One row per form submission — all question responses, metadata, and system fields     |
| Cases  | One row per case — current properties, status, open/close dates, and linked user info |

## Forms

Forms represent individual data collection events. Each row is one submission from a mobile worker.

#### Form metadata fields

| Field                | Description                                                         |
| -------------------- | ------------------------------------------------------------------- |
| `form_id`            | Unique identifier for the submission                                |
| `xmlns`              | The form definition namespace (identifies which form type was used) |
| `received_on`        | Timestamp when the server received the submission                   |
| `server_modified_on` | Last modified timestamp on the server                               |
| `app_id`             | The CommCare app that generated the submission                      |
| `build_id`           | Specific app build version used                                     |
| `user_id`            | ID of the mobile worker who submitted the form                      |
| `username`           | Username of the mobile worker                                       |
| `device_id`          | Device identifier                                                   |
| `version`            | Form version                                                        |

#### Form response fields

Question responses are included as individual columns. The exact column names depend on your form definition — each question in your CommCare form becomes a column in the exported data.

## Cases

Cases track individuals, households, or other entities over time. Each row represents one case with its current state.

#### Case fields

| Field                  | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `case_id`              | Unique identifier for the case                 |
| `case_type`            | Type of case (e.g., patient, household, farm)  |
| `case_name`            | Human-readable name for the case               |
| `owner_id`             | User or group that owns the case               |
| `opened_on`            | When the case was first created                |
| `closed_on`            | When the case was closed (if applicable)       |
| `closed`               | Boolean — whether the case is currently closed |
| `server_last_modified` | Last time the case was updated on the server   |
| `external_id`          | Optional external reference ID                 |
| `indices`              | Linked parent case references                  |

#### Case properties

Like form responses, case properties depend on your CommCare project configuration. Custom case properties you've defined in your app appear as additional columns.

## Common data combinations

* **Join Forms + Cases** on `case_id` to connect individual submissions to the cases they updated
* **Append Forms** from multiple project spaces into one sheet to compare activity across regions or programs
* **Aggregate Forms** by `username` and date to build mobile worker performance summaries

## Use cases by role

{% tabs %}
{% tab title="Program managers" %}

* Track case status and closure rates across field teams
* Monitor form submission volumes by worker or location over time
* Identify gaps in data collection by filtering cases with no recent form updates
  {% endtab %}

{% tab title="Data analysts" %}

* Join form submissions to cases to build longitudinal datasets
* Aggregate survey responses to calculate program indicators (e.g., vaccination rates, visit completion)
* Feed CommCare data into BigQuery for SQL-based analysis alongside other program data sources
  {% endtab %}

{% tab title="Field supervisors" %}

* Pull daily form submissions into Google Sheets to review worker activity
* Use ChatGPT or Claude as an AI destination to summarize field reports or flag anomalies
* Monitor open case counts by owner to manage workload distribution
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Column names for form responses and case properties vary by project — your export will only contain the fields defined in your specific CommCare app
* The `start_date` filter applies to the `received_on` field for Forms and `server_last_modified` for Cases
* Archived or deleted cases may not appear in exports depending on your CommCare HQ plan and API access level
* Multi-select question responses are typically returned as space-separated strings

## CommCare common issues

### Connection issues

<details>

<summary>Authentication failed — invalid API key</summary>

Double-check that you copied your full API key from CommCare HQ without any extra spaces. To find it, log in to CommCare HQ, click your username in the top right, go to **Settings**, and look for the **API Key** section. If you've recently regenerated your key, make sure you're using the new one.

</details>

<details>

<summary>Project Space not found</summary>

The Project Space name must match exactly what appears in your CommCare HQ URL — for example, if your URL is `www.commcarehq.org/a/my-project/`, the project space is `my-project`. It's case-sensitive and must not include slashes.

</details>

<details>

<summary>Connection works but returns no data</summary>

Check your start date setting. If you've set a start date far in the future, no records will match. Use the date picker to set a date in the past — at least far enough back to capture some submissions — and run the data flow again.

</details>

### Missing data

<details>

<summary>Some form submissions are missing from the export</summary>

CommCare processes submissions asynchronously, so there can be a delay between when a form is submitted offline and when it appears in the API. If a mobile worker had poor connectivity, their submissions may arrive hours or days later. Use a start date that gives enough buffer to capture delayed syncs.

</details>

<details>

<summary>Case properties I expect are not showing up as columns</summary>

Case properties in CommCare are dynamic and depend on your app configuration. If a case has never had a particular property set, it won't appear as a column. Check that the cases in your export have actually had those properties filled in via a form submission.

</details>

<details>

<summary>Closed cases are not appearing in the export</summary>

By default, the Cases entity returns all cases including closed ones. If closed cases are missing, verify that your CommCare HQ API access level allows retrieving closed cases — this can vary by plan.

</details>

### Permission errors

<details>

<summary>403 Forbidden error when running the data flow</summary>

This usually means your CommCare account does not have API access enabled. CommCare requires a **Standard plan or higher** to use the API. Check your CommCare HQ subscription, or contact your project administrator to confirm your account has the right permissions.

</details>

<details>

<summary>Can only see some cases or forms, not all</summary>

Your CommCare user account may only have access to cases owned by your user or group, not the entire project. Ask your CommCare project admin to grant your API user account project-level data access.

</details>

### Data discrepancies

<details>

<summary>Row counts don't match what I see in CommCare HQ</summary>

CommCare HQ's reporting interface sometimes excludes test submissions or archived records. The API may return more rows than the UI shows. Check whether test users or test submissions are included in your export and filter them out in your destination if needed.

</details>

<details>

<summary>Dates look incorrect or are in the wrong timezone</summary>

CommCare stores timestamps in UTC. If your reports expect local time, you'll need to convert the timestamp columns in your destination (e.g., using a formula in Google Sheets or a transformation in BigQuery).

</details>

### Rate limits

<details>

<summary>Export is very slow or times out for large projects</summary>

CommCare's API can be slow for projects with tens of thousands of forms or cases. Use the start date filter to limit the volume of records per export. For large historical datasets, consider breaking exports into smaller date ranges using separate data flows and using the Append transformation to combine them.

</details>

## CommCare FAQ

<details>

<summary>Can I connect multiple CommCare project spaces in one data flow?</summary>

Yes. Add each project space as a separate source within the same data flow. Then use the **Append** transformation to stack the data into a single table. This is useful if your organization runs the same program across multiple regions, each with its own CommCare project.

</details>

<details>

<summary>Where do I find my CommCare API key?</summary>

Log in to CommCare HQ, click your username in the top-right corner, and go to **Settings**. You'll find an **API Key** section where you can view or regenerate your key. If you don't see this option, your account may not have API access — check your CommCare plan.

</details>

<details>

<summary>How does the start date filter work?</summary>

The start date filters Forms by their `received_on` timestamp and Cases by `server_last_modified`. Only records on or after your chosen start date are included. Use the date picker in the data flow settings to set this — there are no text-based date macros.

</details>

<details>

<summary>Why do my form columns change between exports?</summary>

CommCare form fields are dynamic — they're based on your app's form definition. If your CommCare app is updated with new or renamed questions, the column structure of your export will change to match. This can break formulas or dashboards that reference specific column names, so test after any app update.

</details>

<details>

<summary>Can I export data from a CommCare Community (free) plan?</summary>

No. CommCare's API is only available on paid plans (Standard and above). If you're on the Community plan, you'll receive a 403 Forbidden error when trying to connect. You'll need to upgrade your CommCare HQ subscription to use Coupler.io with CommCare.

</details>

<details>

<summary>Can I send CommCare data to AI tools for analysis?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Perplexity, Cursor, and OpenClaw. You can route your CommCare form submissions or case data directly to these tools — useful for summarizing field reports, identifying patterns in survey responses, or generating program narratives.

</details>

<details>

<summary>How do I connect form submissions back to the cases they updated?</summary>

Use the **Join** transformation in your data flow. Both the Forms and Cases entities include `case_id` — join on this field to create a combined dataset showing which forms were submitted for each case. This is the most effective way to build longitudinal program records.

</details>

<details>

<summary>Are deleted or archived cases included in the export?</summary>

This depends on your CommCare HQ plan and API permissions. In most cases, archived records are excluded from the default API response. If you need to audit deleted data, contact CommCare support directly — this isn't configurable within Coupler.io.

</details>

{% hint style="info" %}
For details on all available fields and how to combine entities, see the [Data Overview](#commcare-data-overview) article. If you're hitting connection or permission errors, check [Common Issues](#commcare-common-issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/other/commcare.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.