CommCare API Overview

This page below provides an overview of CommCare’s API functionality.

1 Overview
2 API Versioning
3 API Authentication
- 3.1 Basic authentication
- 3.2 API Key authentication
- 3.3 Two-Factor authentication
4 API Explorer
5 API Standards
- 5.1 Dates
- 5.2 Formats
- 5.3 Objects, Types, and IDs
- 5.4 Lists
6 Standards used in Some APIs
7 Documented APIs and use of Standards
8 API Clients
9 API Key Restrictions
10 API Rate Limiting

Overview

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

API Versioning

The CommCareHQ API is comprised of resources, representing individual data
models. Each resource may contain multiple endpoints (list, detail, etc), and
may have multiple versions.

Some changes are occasionally made to individual resources. Where possible,
these are done in a backwards-compatible manner that should not disrupt existing
integrations. Otherwise, we will introduce a new version of that resource so new
integrations can make use of the updated functionality without impacting
existing integrations.

Here are examples of some changes we consider backwards compatible.

Adding a new field to the response
Adding a new query parameter that can be used to filter the data returned or
to control the serialization
Adding a new option for an existing field or parameter
Adding an additional endpoints or request methods for an existing resource
(eg: adding POST handlers to an API that previously only supported GET
requests)

API Authentication

The API's support a few different methods of authentication in addition to the normal session-based authentication used on the rest of CommCare HQ. This makes it easy to access these URLs programmatically.

The examples below use cURL.

Basic authentication

See Basic access authentication for details of basic authentication.

Example (will prompt for the password):

curl -v -u [USERNAME] '[URL]'

You can also include the password in the command as follows:

curl -v -u [USERNAME]:[PASSWORD] '[URL]'

API Key authentication

Your API Keys can be found at Log In :: CommCare HQ - CommCare HQ.

From that page you can generate new API keys and scope them to individual IP addresses. If an API key has an IP address whitelist, any request originating from a different IP address that uses that API key will be rejected.

When an API key is deleted, all requests using that key will be rejected. Unfortunately deleted keys cannot be recovered.

When creating a new API key, the actual key will only be shown once so you should note it down at that moment.

If you use this method of authentication, you do not need to provide a 2 factor OTP header (this is only relevant for API calls with 2 factor auth required.)

curl -H "Authorization: ApiKey [USERNAME]:[API_KEY]" '[URL]'

Two-Factor authentication

If you have two factor authentication (2FA) set up on your account, then basic authentication is not directly supported for accessing APIs. Instead, you must use Api Key authentication, as described above, or pass in a two factor token generated via SMS or your authenticator application via the "otp" url parameter. For example: https://www.commcarehq.org/a/<domain>/api/v0.5/case/?otp=123456

API Explorer

A tool for browsing the read-only CommCare APIs can be found at CommCare API (and Report) Explorer . This tool will connect directly to your CommCare account using OAuth 2.0 — OAuth so you don't have to worry about handling authentication. See API Explorer for more information.

API Standards

This page contains some shared information about all our APIs.

Dates

We need to decide on a standardized date and datetime format. We will most likely go with ISO 8601.

Formats

All APIs will be available in both JSON and XML format. Because XML is a more complex representation than JSON, there is not a simple 1:1 mapping. However, we will base the APIs on the JSON format and define a consistent schema for converting JSON to XML for consistency. Here are some standards that we're using.

Objects, Types, and IDs

Root objects should always have a type and id property. The type will be used to define the XML element name of the object, and the ID will be tagged as an attribute on the root element. Here is a very simple example demonstrating this:

Sample Object JSON

{ type: "myobject",
  id: "objectid5342",
  name: "An Object",
  color: "green"
}

Sample Object XML

<myobject id="objectid5342">
    <name>An Object</name>
    <color>green</color>
</myobject>

Lists

In JSON lists are allowed to be either very simple lists of a single basic value (typically a string), or lists of objects. Flat lists will be converted to XML as follows:

Sample Object with List JSON

{ type: "myobject",
  id: "objectid5342",
  name: "An Object",
  colors: ["green", "blue", "purple"]
}

Sample Object with List XML

<myobject id="objectid5342">
    <name>An Object</name>
    <colors>
        <color>green</color>
        <color>blue</color>
        <color>purple</color>
    </colors>
</myobject>

The choice of element name for the internal list items (in this case "color") will be defined statically, per element, or may be guessed if there is no static mapping. Typically guessing would entail removing a trailing "s" from the list property name, as in this example.

Lists of objects expect the type property to be present on the object to choose the inner element name, although if none is present will use either a static mapping or guess. The ID attribute is optional but will be treated as described above if present. Root lists of objects should be wrapped in a one-element dictionary, the key of which represents the root element name. The following example shows a basic list of objects. If types are defined it is illegal for any object in the list to have a type different from the others.

Sample List of Objects JSON

{objectcollection: [
    { 
        type: "myobject",
        id: "1",
        name: "A clover",
        color: "green"
    },
    { 
        type: "myobject",
        id: "2",
        name: "The sky",
        color: "blue"
    },
    { 
        type: "myobject",
        id: "3",
        name: "Minda",
        color: "purple"
    }
]}

Sample List of Objects XML

<objectcollection>
    <myobject id="1">
        <name>A clover</name>
        <color>green</color>
    </myobject>
    <myobject id="2">
        <name>The sky</name>
        <color>blue</color>
    </myobject>
    <myobject id="3">
        <name>Minda</name>
        <color>purple</color>
    </myobject>
</objectcollection>

Standards used in Some APIs

Standard	Description

Standard	Description
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.)
casexml20^†	XML spec for case-related transactions. (Taken care of by default by CommCare HQ.)
CentralAuthAPI^†	How authentication is done between a CommCare device and the server
CommCare20Specs^†	Additional documentation for CommCare APIs

^† External links to the JavaRosa/CommCare docs

Documented APIs and use of Standards

All the APIs are documented here.

In the above, [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. You can read more about this under CommCare API Overview | API Authentication .

API Clients

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

Python
- GitHub - dimagi/commcare-hq-api: Work-in-progress Python library for accessing CommCare HQ API end-points.

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.

API Rate Limiting

CommCare applies API rate limits on all project spaces at all times. You can read more about rate limiting here: https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143956626/CommCare+Rate+Limiting#API-Rate-Limiting

CommCare Help Site