This feature requires a CommCare Software Plan

This feature (API Access) is only available to CommCare users with a Standard 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

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: http://www.cs.sunysb.edu/documentation/curl/

- 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 the Authentication page for information about how to authenticate your requests with CommCare HQ.

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.

API

Description

URL Endpoint

Permission required 

Submission

API to submit data to CommCareHQ.

See Documentation

Set per domain
User Creation (Mobile Worker)API to create a mobile worker on CommCareHQhttps://www.commcatehq.org/a/[domain]/api/[version]/user/Edit Mobile Workers
User Edit (Mobile Worker)API to edit a mobile worker on CommCareHQhttps://www.commcarehq.org/a/[domain]/api/[version]/user/[idEdit Mobile Workers
User Delete (Mobile Worker)API to delete a mobile worker on CommCareHQhttps://www.commcarehq.org/a/[domain]/api/[version]/user/[id]Edit Mobile Workers
User Creation (Web User)API to create a web user on CommCareHQhttps://www.commcarehq.org/a/[domain]/api/[version]/web-user/ Edit Web Users
Create GroupAPI to create a mobile worker group on CommCareHQhttps://www.commcatehq.org/a/[domain]/api/[version]/group/Edit Mobile Workers
Edit GroupAPI to edit a mobile worker group on CommCareHQhttps://www.commcatehq.org/a/[domain]/api/[version]/group/[id]Edit Mobile Workers 
User Edit (Web User)API to edit a web user on CommCareHQhttps://www.commcarehq.org/a/[domain]/api/[version]/web-user/[id]Edit Web Users

User Registration

API for registering users on CommCareHQ.

https://www.commcarehq.org/a/\[domain\]/receiver

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

See Documentation

Set per domain

Groups

list groups

https://www.commcarehq.org/a/[domain]/api/[version]/group/

Edit Mobile Workers

Mobile Workers

list mobile workers or access individual user data

https://www.commcarehq.org/a/[domain]/api/[version]/user/

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

Cases

list cases

https://www.commcarehq.org/a/[domain]/api/[version]/case/

Edit Data

Case Data

find a single case

https://www.commcarehq.org/a/[domain]/api/[version]/case/[case_id]/

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
Data Forwardingmanage your data forwarding endpointshttps://www.commcarehq.org/a/[domain]/api/[version]/data-forwarding/Domain Admin
Application Structureview the schema of modules, cases, and forms for your applicationhttps://www.commcarehq.org/a/[domain]/api/[version]/application/Edit Apps
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 documentation  
Lookup Table UploadCreate or edit lookup tables by uploading excel file containing table dataSee documentation  
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

Standards used in APIs

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

Case XML

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

Authentication

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

Enabling Data Integration 

How to enable Forms and Case Forwarding

API Clients

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

 

 

  • No labels

1 Comment

  1. Anonymous

    https://www.commcatehq.org/a/[domain]/api/[version]/user/