Popular Help Content

No popular content.

This feature requires a CommCare Software Plan

This feature (API Access) is only available to CommCare users with a Pro Plan or higher. For more details, see the CommCare Software Plan page.

This section is for you if...

- You are a programmer 

- You are looking to write code that interacts directly with CommCare HQ through its APIs

If you are not a programmer and are looking to integrate CommCare with other platforms we recommend looking at our Zapier Integration.

Things we take for granted...

- You should have a familiarity with HTTP conventions, such as GET and POST and url parameters

- To follow the examples, you should be familiar with the standard command line tool curl. Here's the manual: https://curl.haxx.se/docs/

- Character encoding is UTF-8. Dates should be compliant ISO 8601. (In some cases we're still using RFC 3339, but we're moving towards ISO 8601.) Guids should be generated in accordance with RFC 4122.


Read the Authentication page for information about how to authenticate your requests with CommCare HQ.

API Explorer

A tool for browsing the read-only CommCare APIs can be found at https://commcare-api-explorer.dimagi.com/. This tool will connect directly to your CommCare account using Oauth2 so you don't have to worry about handling authentication.

Documented APIs and use of Standards

In the following, [version] should always be replaced with one of v0.5, v0.4. These documents only describe the latest version - some prior versions remain available only to support backwards compatibility with deployed systems, not for general use.

The latest version is v0.5.

In addition to the permissions listed, all APIs also require the "API Access" permission. The URL endpoints listed below should be utilized as part of a curl authentication command. For more information, please review CommCare's API Authentication Documentation.



URL Endpoint

Permission required


API to submit data to CommCare HQ.

See Documentation

Set per domain
Bulk Upload APIPerforms Bulk Imports of Case Data through the Excel Case Data Importer to either create or update casesSee DocumentationValid login
User Creation (Mobile Worker)API to create a mobile worker on CommCare HQhttps://www.commcarehq.org/a/[domain]/api/[version]/user/Edit Mobile Workers
User Edit (Mobile Worker)API to edit a mobile worker on CommCare HQhttps://www.commcarehq.org/a/[domain]/api/[version]/user/[idEdit Mobile Workers
User Delete (Mobile Worker)API to delete a mobile worker on CommCare HQhttps://www.commcarehq.org/a/[domain]/api/[version]/user/[id]Edit Mobile Workers

User Registration

API for registering users on CommCare HQ.


Set per domain

OTA Restore (Case List)

API to retrieve data payload consumable to restore a users current state of cases.

See Documentation

Valid login

Data Export

API to export data from CommCare HQ.

See Documentation

Set per domain


List, create, edit and delete groups

See Documentation

Edit Mobile Workers

Mobile Workers

list mobile workers or access individual user data


Edit Mobile Workers

Web Users

list web users or access individual user datahttp://www.commcarehq.org/a/[domain]/api/ [version] /web-user/Edit Web Users


List locations and location types and view their detailsSee documentationValid login
SMS Mobile Worker Registration APIAPI to initiate the SMS Mobile Worker Registration workflowhttps://www.commcarehq.org/a/[domain]/api/[version]/sms_user_registration/Edit Data
Send CommCare Install Info over SMSAPI to facilitate the reinstallation of CommCare for already-registered usershttps://www.commcarehq.org/a/[domain]/api/[version]/sms_user_registration_reinstall/Edit Data


list cases


Edit Data

Case Data

find a single case


Edit Data
Formslist form submissionshttps://www.commcarehq.org/a/[domain]/api/[version]/form/Edit Data
Form Datalist/search forms or access a single formhttps://www.commcarehq.org/a/[domain]/api/[version]/form/[form_id]/Edit Data
Application Structureview the schema of modules, cases, and forms for your applicationhttps://www.commcarehq.org/a/[domain]/api/[version]/application/Edit Apps
User IdentityLook up user detailshttps://www.commcarehq.org/api/[version]/identity/Valid login
User Domain ListLook up user domainshttps://www.commcarehq.org/api/[version]/user_domains/Valid login
Single Sign Oncheck login credentials and get the user detailshttps://www.commcarehq.org/a/[domain]/api/[version]/sso/Valid login
Form AttachmentsAPI to get an attachment from a formhttps://www.commcarehq.org/a/[domain]/api/form/attachment/{form_id}/{attachment_name}Valid login
Case AttachmentsAPI to get an attachment from a casehttps://www.commcarehq.org/a/[domain]/api/case/attachment/{form_id}/{ attachment_name}Valid login
Lookup Table DownloadGet lookup table dataSee documentationEdit Apps
Lookup Table UploadCreate or edit lookup tables by uploading excel file containing table dataSee documentationEdit Apps
Download a .ccz fileDownload the .ccz file for a specific version of an applicationSee documentation
List ReportsList the available reports in the projecthttps://www.commcarehq.org/a/[PROJECT]/api/v0.5/simplereportconfiguration/?format=jsonDomain Admin
Download Report DataFilter and download data for a specific reporthttps://www.commcarehq.org/a/[PROJECT]/api/v0.5/configurablereportdata/REPORTID/View Data

Enabling Data Integration 

Connecting to Google Sheets, Email and more using Zapier

How to enable Forms and Case Forwarding

API Clients

Note that any third party libraries are not supported by Dimagi.

API Key Restrictions

API Keys can be restricted by two methods IP address and/or Domain. 

  • The IP Allowlist restriction defines a specific IP address or comma separated list of IP addresses where the API Key can be used. The field references IPv4. There are many ways to check what your IP Address is, one simple way is to use: https://whatismyipaddress.com/
  • The Domain restriction allows an API Key to be restricted to a specific domain/project space.

If either of these fields are left blank, the API Key will by default be unrestricted.

Standards used in Some APIs



OpenRosa Request

The standard for HTTP(S) interactions between CommCare client and server

Meta Data Schema

Open Rosa standard meta data tags. (Taken care of by default by CommCare HQ.)

Case XML

XML spec for case-related transactions. (Taken care of by default by CommCare HQ.)


How authentication is done between a CommCare device and the server 

CommCare 2.0 Specs Additional documentation for CommCare APIs

 External links to the JavaRosa/CommCare docs

API Rate Limiting

CommCare applies API rate limits on all project spaces at all times.

Standard rate limit thresholds

  • The standard rate limit per minute is 3 API requests per mobile worker.

  • The standard rate limit per hour is 130 API requests per mobile worker.

  • The standard rate limit per day is 1000 API requests per mobile worker.

In the table below, you will see the calculated rate limit thresholds for each subscription plan.

(number of mobile workers) * (standard API requests per minute or hour or day etc.)




Standard plan

125 mobile workers

API requests per minute


API requests per hour


API requests per day


Pro plan

250 mobile workers

API requests per minute


API requests per hour


API requests per day


Advanced plan

500 mobile workers

API requests per minute


API requests per hour


API requests per day


Enterprise Plan

1000 mobile workers

API requests per minute


API requests per hour


API requests per day


Technically Feasible API Requests

We advise you to adhere to the rate limits as outlined above.

  • No labels