Newer version available

A newer version of this API is available. See List Cases (version 3+).

 

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/[version]/case/

Input parameters:

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

NameDescriptionExampleStatus
user_idUser UUID (optional)user_id=3c5a623af057e23a32ae4000cf291339(tick) Supported
typeType of case (optional)type=pregnant_mother(tick) Supported
closedCase status (optional)
Supported: false (default), true, any 
closed=any(tick) Supported
limitThe maximum number of records to return. Default: 20. Maximum: 100limit=25(tick) Supported
offsetThe number of records to offset in the results. Default: 0.

offset=100

(tick) Supported
date_modified_startReturn records only modified since this datedate_modified_start=2001-01-01T12:37:00Z(tick) Supported
date_modified_endReturn records only modified until this datedate_modified_end=2002-01-01T12:57:00Z(tick) Supported
server_date_modified_startReturn records where the server's date modified is after the given dateserver_date_modified_start=2001-01-01T12:37:00Z(tick) Supported
server_date_modified_endRecords where the server's date modified is before the given dateserver_date_modified_end=2002-01-01T15:22:00Z(tick) Supported
[ property ]Any case propertyname=NEAL&properties/favorite_color=blue(tick) Supported

Output values:

NameDescriptionExample
case_idCase UUID0X9OCW3JMV98EYOVN32SGN4II
usernameUser name of case owner, including domainjdoe@example.commcarehq.org
user_idUUID user that owns the case3c5a623af057e23a32ae4000cf291339
owner_idUUID group/user that owns the caseac9d34ff59cf6388e4f5804b12276d8a
case_nameName of caseRose
external_idExternal ID associated with the case123456
case_typeType of casepregnant_mother
date_openedDate and time case was opened2011-11-16T14:26:15Z
date_modifiedDate and time case was last modified2011-12-13T15:09:47Z
closedCase statusfalse
date_closedDate and time case was closed2011-12-20T15:09:47Z

Sample usage:

https://www.commcarehq.org/a/[domain]/api/v0.4/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" : "086a65f65",
        "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" ]
  },
  ...
]
  • No labels

1 Comment

  1. After considering some potential uses of this API call, I have two suggestions to consider....

    Including case property values in the return data set.  By including case property values in the returned xml/json document, the application could include case property values (e.g. patient name) in the case list without separately fetching information about each case.

    Search criteria.  Would be nice to support flexible query criteria, identical to how the 'Case List' data inspection report supports search criteria.