| Multiexcerpt include macro | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
| Table of Contents |
|---|
This section is for you if...
- You are a programmer
...
| Excerpt |
|---|
CommCare allows programmers to write code that interacts directly with CommCare HQ through |
...
APIs |
...
If you are not a programmer and are looking to integrate CommCare with other platforms we recommend looking at https://dimagi.atlassian.net/wiki/x/fRzKfw.
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.
Authentication
Read Authentication 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 Authentication.
...
API
...
Description
...
URL Endpoint
...
Permission required
...
...
API to submit data to CommCare HQ.
...
See Documentation
...
Set per domain
...
...
Performs Bulk Imports of Case Data through the Excel Case Data Importer to either create or update cases
...
...
Valid login
...
...
API to create a mobile worker on CommCare HQ
...
https://www.commcarehq.org/a/[domain]/api/[version]/user/
...
Edit Mobile Workers
...
...
API to edit a mobile worker on CommCare HQ
...
https://www.commcarehq.org/a/[domain]/api/[version]/user/[id]
...
Edit Mobile Workers
...
...
API to delete a mobile worker on CommCare HQ
...
https://www.commcarehq.org/a/[domain]/api/[version]/user/[id]
...
Edit Mobile Workers
...
...
API for registering users on CommCare HQ.
...
https://www.commcarehq.org/a/\[domain\]/receiver
...
Set per domain
...
...
API to retrieve data payload consumable to restore a users current state of cases.
...
See Documentation
...
Valid login
...
...
API to export data from CommCare HQ.
...
See Documentation
...
Set per domain
...
...
List, create, edit and delete groups
...
See Documentation
...
Edit Mobile Workers
...
...
list mobile workers or access individual user data
...
https://www.commcarehq.org/a/[domain]/api/[version]/user/
...
Edit Mobile Workers
...
...
list web users or access individual user data
...
http://www.commcarehq.org/a/[domain]/api/ [version] /web-user/
...
Edit Web Users
...
...
List locations and location types and view their details
...
...
Valid login
...
SMS Mobile Worker Registration API
...
API to initiate the SMS Mobile Worker Registration workflow
...
https://www.commcarehq.org/a/[domain]/api/[version]/sms_user_registration/
...
Edit Data
...
Send CommCare Install Info over SMS
...
API to facilitate the reinstallation of CommCare for already-registered users
...
https://www.commcarehq.org/a/[domain]/api/[version]/sms_user_registration_reinstall/
...
Edit Data
...
...
list cases
...
https://www.commcarehq.org/a/[domain]/api/[version]/case/
...
Edit Data
...
...
find a single case
...
https://www.commcarehq.org/a/[domain]/api/[version]/case/[case_id]/
...
Edit Data
...
...
list form submissions
...
https://www.commcarehq.org/a/[domain]/api/[version]/form/
...
Edit Data
...
...
list/search forms or access a single form
...
https://www.commcarehq.org/a/[domain]/api/[version]/form/[form_id]/
...
Edit Data
...
...
view the schema of modules, cases, and forms for your application
...
https://www.commcarehq.org/a/[domain]/api/[version]/application/
...
Edit Apps
...
...
Look up user details
...
https://www.commcarehq.org/api/[version]/identity/
...
Valid login
...
...
Look up user domains
...
https://www.commcarehq.org/api/[version]/user_domains/
...
Valid login
...
...
check login credentials and get the user details
...
https://www.commcarehq.org/a/[domain]/api/[version]/sso/
...
Valid login
...
Form Attachments
...
API to get an attachment from a form
...
https://www.commcarehq.org/a/[domain]/api/form/attachment/{form_id}/{attachment_name}
...
Valid login
...
Case Attachments
...
API to get an attachment from a case
...
https://www.commcarehq.org/a/[domain]/api/case/attachment/{form_id}/{ attachment_name}
...
Valid login
...
...
Get lookup table data
...
...
Edit Apps
...
...
Create or edit lookup tables by uploading excel file containing table data
...
...
Edit Apps
...
Download a .ccz file
...
Download the .ccz file for a specific version of an application
...
/wiki/spaces/GTD/pages/2145058940
...
...
List the available reports in the project
...
https://www.commcarehq.org/a/[PROJECT]/api/v0.5/simplereportconfiguration/?format=json
...
Domain Admin
...
...
Filter and download data for a specific report
...
https://www.commcarehq.org/a/[PROJECT]/api/v0.5/configurablereportdata/REPORTID/
...
View Data
Enabling Data Integration
https://dimagi.atlassian.net/wiki/x/TQPKfw
API Clients
Note that any third party libraries are not supported by Dimagi.
Ruby
https://github.com/gdeflaux/commcare_api (third party)
Python
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
...
Standard
...
Description
...
...
The standard for HTTP(S) interactions between CommCare client and server
...
...
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
...
...
Additional documentation for CommCare APIs
† External links to the JavaRosa/CommCare docs
API Rate Limiting
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
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.)
...
MOBILE WORKERS INCLUDED IN THE SUBSCRIPTION
...
TIME PERIOD
...
RATE LIMIT THRESHOLD
...
Standard plan
...
125 mobile workers
...
API requests per minute
...
375
...
API requests per hour
...
16,250
...
API requests per day
...
125,000
...
Pro plan
...
250 mobile workers
...
API requests per minute
...
750
...
API requests per hour
...
32,500
...
API requests per day
...
250,000
...
Advanced plan
...
500 mobile workers
...
API requests per minute
...
1,500
...
API requests per hour
...
65,000
...
API requests per day
...
500,000
...
Enterprise Plan
...
1000 mobile workers
...
API requests per minute
...
3,000
...
API requests per hour
...
130,000
...
API requests per day
...
1,000,000
Technically Feasible API Requests
...
and web hooks. Through this, users can flexibly design how to integrate CommCare into your existing ecosystems. You can read more about APIs on our Read the Docs page: https://commcare-hq.readthedocs.io/api.html |
| Multiexcerpt include macro | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
CommCare API Documentation
| Child pages (Children Display) | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|