Case Data API v1

List Cases

Purpose

Retrieves a list of cases. The list of cases may be presented to the end user as a simple list of cases, where each case name incudes a hyperlink to access detailed information about the case.

Base URL

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

Authentication

For more information, please review API Authentication.

Permission Required

Edit Data

Request & Response Details

Input Parameters

In addition to all Case Data API parameters, you may use the following input parameters to filter results and control paging:

Name	Description	Example	Summary
owner_id	User or Group UUID (optional)	owner_id=ac9d34ff59cf6388e4f5804b12276d8a	All cases owned by that entity (should not use with user)
user_id	User UUID (optional)	user_id=3c5a623af057e23a32ae4000cf291339	All cases last modified by that user
type	Type of case (optional)	type=pregnant_mother	All cases matching the type
closed	Case status (optional)	closed=true	All open/closed/both cases
indexed_on_start	A date (and time). Will return only cases that have had data modified since the passed-in date.	indexed_on_start=2021-01-01 indexed_on_start=2021-01-01T06:05:42	This is the recommended field to use for data pagination. It is very similar to server_date_modified but handles edge cases better.
indexed_on_end	A date (and time). Will return only cases that have had data modified before the passed-in date.	indexed_on_end=2021-01-01 indexed_on_end=2021-01-01T06:05:42	Filters cases modified before this date.
date_modified_start	Modified after this date (phone date)	date_modified_start=2012-05-20 date_modified_start=2013-09-29T10:40Z	Defaults to the first submission date.
date_modified_end	Modified before this date (phone date)	date_modified_end=2012-05-27	Defaults to the current date.
server_date_modified_start	Modified after this date (server date)	server_date_modified_start=2012-05-20	Defaults to the first submission date.
server_date_modified_end	Modified before this date (server date)	server_date_modified_end=2012-05-27	Defaults to the current date.
name	Name	name=NEAL	Case name used for filtering.
limit	The maximum number of records to return.	limit=100	Defaults to 20. Maximum is 5000.
offset	The number of records to offset in the results.	offset=100	Defaults to 0.
external_id	‘external_id’ property	external_id=123abc	Used to filter cases by external ID.
indexed_on	Indexed on date	order_by=indexed_on	Defaults to the oldest indexed_on date.
server_date_modified	Date after which case was modified on the server	order_by=server_date_modified	Defaults to oldest server_date_modified.

Output Values

Name	Description	Example
case_id	Case UUID	0X9OCW3JMV98EYOVN32SGN4II
username	User name of case owner, including domain	jdoe@example.commcarehq.org
user_id	UUID user that owns the case	3c5a623af057e23a32ae4000cf291339
owner_id	UUID group/user that owns the case	ac9d34ff59cf6388e4f5804b12276d8a
case_name	Name of case	Rose
external_id	External ID associated with the case	123456
case_type	Type of case	pregnant_mother
date_opened	Date and time case was opened	2011-11-16T14:26:15Z
date_modified	Date and time case was last modified	2011-12-13T15:09:47Z
closed	Case status	false
date_closed	Date and time case was closed	2011-12-20T15:09:47Z

Sample Usage

https://www.commcarehq.org/a/[domain]/api/case/v1/?format=xml

Sample XML Output

<cases>
    <case>
        <case_id>0X9OCW3JMV98EYOVN32SGN4II</case_id>
        <username>jdoe@example.commcarehq.org</username>
        <user_id>3c5a623af057e23a32ae4000cf291339</user_id>
        <owner_id>3c5a623af057e23a32ae4000cf291339</owner_id>
        <case_name>Rose</case_name>
        <external_id>123456</external_id>
        <case_type>pregnancy</case_type>
        <date_opened>2011-11-16T14:26:15</date_opened>
        <date_modified>2011-12-13 15:09:47</date_modified>
        <closed>false</closed>
        <date_closed>2011-12-20 15:09:47</date_closed>
    </case>
    ...
</cases>

Sample JSON Output

[
  {
    "case_id": "45WKYXQRFFU3AT4Y022EX7HF2",
    "closed": false,
    "date_closed": null,
    "date_modified": "2012-03-13T18:21:52Z",
    "domain": "demo",
    "indices": {},
    "properties": {
      "case_name": "ryan",
      "case_type": "programmer",
      "date_opened": "2012-03-13T18:21:52Z",
      "external_id": "45WKYXQRFFU3AT4Y022EX7HF2",
      "gender": "m",
      "languages": "python java javascript c php erlang love",
      "owner_id": null,
      "role": "artisan"
    },
    "server_date_modified": "2012-04-05T23:56:41Z",
    "server_date_opened": "2012-04-05T23:56:41Z",
    "user_id": "06414101dc45bcfdc963b8cb1a1ebdfd",
    "version": "1.0",
    "xform_ids": [ "3HQEXR2S0GIRFY2GF40HAR7ZE" ]
  },
  "..."
]

Case Data Details

Purpose

Retrieve all data associated with a case, including case property values, a list of associated forms, and referrals. The case data may be presented to the end user as a case details screen.

Base URL

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

Authentication

For more information, please review API Authentication.

Permission Required

Edit Data

Request & Response Details

Input Parameters

Name	Description	Values	Example	Status
format	Return data format	xml, json	format=xml	Supported
properties	Whether to include properties	all, none	properties=all	Proposed
indices	Whether to include indices	all, none	indices=all	Proposed
xforms_by_name__full	Whether to include all xforms by name	true	xforms_by_name__full=true	Supported
xforms_by_xmlns__full	Whether to include all xforms by xmlns	true	xforms_by_xmlns__full=true	Supported
child_cases__full	Whether to include child cases	true	child_cases__full=true	Supported since version 4
parent_cases__full	Whether to include parent cases	true	parent_cases__full=true	Supported since version 4

Output Values

Case Metadata

Name	Description	Example
case_id	Case UUID	0X9OCW3JMV98EYOVN32SGN4II
user_name	User name of case owner, including domain	jdoe@example.commcarehq.org
user_id	UUID of user that owns the case	3c5a623af057e23a32ae4000cf291339
date_modified	Date and time case was last modified	2011-12-13T15:09:47Z
closed	Status of the case (open, closed)	false
date_closed	Date and time case was closed	2011-12-20T15:09:47Z
properties	List of all editable case properties, including both special predefined properties and user-defined dynamic properties

Special Case Properties

Name	Description	Example
owner_id	ID of the owner of the case (can be user or group)
case_name	Name of case	Rose
external_id	External ID associated with the case	123456
case_type	Type of case	pregnancy
date_opened	Date and time case was opened	2011-11-16T14:26:15Z
indices	End of special properties with a list of references to other cases with properties <case_type/> and <case_id/>

Start for Forms Associated with the Case. This repeats for each form, as seen in sample output below

Name	Description	Example
form_id	UUID of form associated with the case	1J9NF7B4FTH73435PYJJSL5SJ
form_name	Name of form associated with the case	Prenatal visit
started_on	Date and time form was started	2011-11-16T14:26:15Z
ended_on	Date and time form was completed	2011-11-16T14:27:35Z

Sample Usage

https://www.commcarehq.org/a/demo/api/case/v1/0X9OCW3JMV98EYOVN32SGN4II/?format=xml&properties=all&indices=all

Sample Output

<case>
    <domain>example</domain>
    <case_id>0X9OCW3JMV98EYOVN32SGN4II</case_id>
    <username>jdoe@example.commcarehq.org</username>
    <user_id>3c5a623af057e23a32ae4000cf291339</user_id>
    <closed>false</closed>
    <date_closed>2011-12-20 15:09:47Z</date_closed>
    <date_modified>2011-12-13 15:09:47Z</date_modified>
    <properties>
        <case_name>Rose</case_name>
        <case_type>pregnancy</case_type>
        <date_opened>2011-11-16T14:26:15Z</date_opened>
        <external_id>123456</external_id>
        <owner_id>3c5a623af057e23a32ae4000cf291339</owner_id>
        <case_property1>Dynamic property value 1</case_property1>
        <case_property2>Dynamic property value 2</case_property2>
        ...
    </properties>
    <indices>
        <case_ref1>
            <case_type>other_case_type</case_type>
            <case_id>8GPM05TVPIUH0Q4XLXVIURRTA</case_id>
        </case_ref1>
        ...
    </indices>
    <forms>
        <form>
            <form_id>1J9NF7B4FTH73435PYJJSL5SJ</form_id>
            <form_name>Prenatal visit</form_name>
            <started_on>2011-11-16T14:26:15Z</started_on>
            <ended_on>2011-11-16T14:27:35Z</ended_on>
            <properties>
                <form_property1>Dynamic property value 1</form_property1>
                <form_property2>Dynamic property value 2</form_property2>
                ...
            </properties>
        </form>
        ...
    </forms>
    <referrals>
        <referral>
            <referral_id>D8LZS28LEUWU7W9QNDM89XWPL</referral_id>
            <referral_type>referred_to_health_center</referral_type>
            <opened_on>2011-11-17T14:26:15Z</opened_on>
            <modified_on>2011-11-17T14:27:10Z</modified_on>
            <followup_on>2011-11-19T00:00:00Z</followup_on>
            <referral_status>open</referral_status>
        </referral>
        ...
    </referrals>
    ...
</case>