1.68 Enrollment instance query

To query for tracked entity instances you can interact with the /api/enrollments resource.

/api/26/enrollments

1.68.1 Request syntax

Tracked entity instances query parameters
Query parameter Description
ou Organisation unit idenfiers, separated by “;”.
ouMode The mode of selecting organisation units, can be SELECTED | CHILDREN | DESCENDANTS | ACCESSIBLE | ALL. Default is SELECTED, which refers to the selected organisation units only. See table below for explanations.
program Program identifier. Restricts instances to being enrolled in the given program.
programStatus Status of the instance for the given program. Can be ACTIVE | COMPLETED | CANCELLED.
followUp Follow up status of the instance for the given program. Can be true | false or omitted.
programStartDate Start date of enrollment in the given program for the tracked entity instance.
programEndDate End date of enrollment in the given program for the tracked entity instance.
trackedEntity Tracked entity identifer. Restricts instances to the given tracked instance type.
trackedEntityInstsane Tracked entity instance identifier. Should not be used together with trackedEntity.
page The page number. Default page is 1.
pageSize The page size. Default size is 50 rows per page.
totalPages Indicates whether to include the total number of pages in the paging response (implies higher response time).
skipPaging Indicates whether paging should be ignored and all rows should be returned.

The available organisation unit selection modes are explained in the following table.

Organisation unit selection modes
Mode Description
SELECTED Organisation units defined in the request (default).
CHILDREN Immediate children, i.e. only the first level below, of the organisation units defined in the request.
DESCENDANTS All children, i.e. at only levels below, e.g. including children of children, of the organisation units defined in the request.
ACCESSIBLE All descendants of the data view organisation units associated with the current user. Will fall back to data capture organisation units associated with the current user if the former is not defined.
ALL All organisation units in the system. Requires authority.

You can specify queries with words separated by space - in that situation the system will query for each word independently and return records where each word is contained in any attribute. A query item can be specified once as an attribute and once as a filter if needed. The query is case insensitive. The following rules apply to the query parameters.

  • At least one organisation unit must be specified using the ou parameter (one or many), or ouMode=ALL must be specified.

  • Only one of the program and trackedEntity parameters can be specified (zero or one).

  • If programStatus is specified then program must also be specified.

  • If followUp is specified then program must also be specified.

  • If programStartDate or programEndDate is specified then program must also be specified.

A query for all instances associated with a specific organisation unit can look like this:

/api/26/enrollments.json?ou=DiszpKrYNg8

To constrain the response to instances which are part of a specific program you can include a program query parameter:

/api/26/enrollments.json?ou=O6uvpzGd5pu&ouMode=DESCENDANTS&program=ur1Edk5Oe2n

To specify program enrollment dates as part of the query:

/api/26/enrollments.json?&ou=O6uvpzGd5pu&program=ur1Edk5Oe2n&programStartDate=2013-01-01&programEndDate=2013-09-01

To constrain the response to instances of a specific tracked entity you can include a tracked entity query parameter:

/api/26/enrollments.json?ou=O6uvpzGd5pu&ouMode=DESCENDANTS&trackedEntity=cyl5vuJ5ETQ

To constrain the response to instances of a specific tracked entity instance you can include a tracked entity instance query parameter, in this case we are restricted it to available enrollments viewable for current user:

/api/26/enrollments.json?ouMode=ACCESSIBLE&trackedEntityInstance=tphfdyIiVL6

By default the instances are returned in pages of size 50, to change this you can use the page and pageSize query parameters:

/api/26/enrollments.json?ou=O6uvpzGd5pu&ouMode=DESCENDANTS&page=2&pageSize=3

1.68.2 Response format

This resource supports JSON, JSONP, XLS and CSV resource representations.

  • json (application/json)

  • jsonp (application/javascript)

  • xml (application/xml)

The response in JSON/XML is in object format and can look like the following (please note that field filtering is supported, so if you want a full view, you might want to add fields=*):

{
    "enrollments": [
        {
            "lastUpdated": "2014-03-28T05:27:48.512+0000",
            "trackedEntity": "cyl5vuJ5ETQ",
            "created": "2014-03-28T05:27:48.500+0000",
            "orgUnit": "DiszpKrYNg8",
            "program": "ur1Edk5Oe2n",
            "enrollment": "HLFOK0XThjr",
            "trackedEntityInstance": "qv0j4JBXQX0",
            "followup": false,
            "enrollmentDate": "2013-05-23T05:27:48.490+0000",
            "incidentDate": "2013-05-10T05:27:48.490+0000",
            "status": "ACTIVE"
        }
    ]
}