List Cases (version 3+)
- Cory Zue
- Krinda Wernicke
- Simon Kelly
Purpose: get a list of cases. The list of cases may be presented to the end user 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/v0.5/case/
Authentication: For more information, please review https://dimagi.atlassian.net/wiki/x/LwXKfw.
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 | |
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 | Modifed 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 | Modifed before this date (server date) | server_date_modified_end=2012-05-27 | Defaults to the current date. |
name | Name | name=NEAL | |
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 | |
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 in 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/v0.5/case/?format=xml
Sample XML output (Proposed):
<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:
JSON Format
[ { "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" ]
},
...
]