CommCare API Overview

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

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: curl - Documentation Overview.

• 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 https://en.wikipedia.org/wiki/CURL. 

Basic authentication

See https://en.wikipedia.org/wiki/Basic_access_authentication for details of basic authentication.

Example (will prompt for the password):

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

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.

Open

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

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

Sample Object XML

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

Sample Object with List XML

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

Sample List of Objects XML

Standards used in Some APIs

^† External links to the JavaRosa/CommCare docs

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

Enabling Data Integration 

https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143951997

https://dimagi.atlassian.net/wiki/x/TQPKfw

API Clients

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

• Python

  • https://github.com/dimagi/commcare-hq-api

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