querySubjects

This method returns a list of subjects owned by the current user.

This method was added in Cortex 2.1

Parameters

Name	Type	Required	Description
cortexToken	string	yes	A token returned by authorize.
query	object	yes	An object to filter the subjects.
orderBy	array of objects	yes	Specify how to sort the subjects.
limit	number	no	The maximum number of subjects that this method should return. A limit of zero means no maximum.
offset	number	no	The number of subjects that this method should skip before returning the result. If the limit is zero, then Cortex will ignore this parameter.

Depending on the query, this method may return a lot of subjects. To avoid performance issues, you should always set an offset and a limit.

query

The query object can contain one or more of these fields:

Name	Type	Description
uuid	string	Set this parameter to get a subject by its id.
subjectName	string	Set this parameter to filter the subjects by name.
sex	string	Set this parameter to filter the subjects by their gender. Must be "M", "F" or "U".
countryCode	string	Set this parameters to filter the subjects by their country.
dateOfBirth	object	An object with fields "from" and "to" to filter the subjects by their date of birth.
keyword	object	An object with the fields as the keyword to search and values are the list of fields to search. The list of fields to search can contains "subjectName", "lastName", "email"

orderBy

The orderBy parameters is an array of objects, similar to the orderBy clause of a SQL request.

Each object must have a single attribute. The key of the attribute is the name of subject's field you want to order by. The value of the attribute must be "ASC" or "DESC", to order is ascending or descending order.

For example, to order the subjects by their names, in alphabetical order, you must use the object {"subjectName":"ASC"}.

You can order the subjects by these fields: subjectName, dateOfBirth.

limit and offset

These parameters are to implement pagination. It useful if you want to display the subjects in a UI. You must order the results to use these parameters.

First you should call this method with a offset of zero, and a limit of X. In the response, check the value of count. If count is greater than the limit, then you should call this method again with an offset of X. And then with an offset of 2*X, 3*X... until you get all the subjects for your query.

Result

The result is an object that includes these fields:

Name	Type	Description
subjects	array of objects	An array of subject objects.
count	number	The total number of subjects that match the query.
limit	number	The limit you specified in the parameters.
offset	number	The offset you specified in the parameters.

Examples

Find the 10 first female subjects born in 1979 or 1980.

Request

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "querySubjects",
    "params": {
        "cortexToken": "xxx",
        "query": {
            "dateOfBirth": {
                "from": "1979-01-01",
                "to": "1980-12-31"
            },
            "sex": "F",
            "keyword": {
                "yyy":["subjectName", "email"]
            }
        },
        "orderBy": [
            {"subjectName": "ASC"}
        ],
        "offset": 0,
        "limit": 10
    }
}

Response

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "count": 1,
        "limit": 10,
        "offset": 0,
        "subjects": [
            {
                "attributes": [
                    {
                        "name": "Handedness",
                        "value": "Left"
                    },
                    {
                        "name": "Education",
                        "value": "Master's degree"
                    }
                ],
                "city": "London",
                "countryCode": "GB",
                "countryName": "",
                "dateOfBirth": "1980-12-25",
                "experimentsCount": 0,
                "modifiedDatetime": "2019-07-01T11:23:11.644+07:00",
                "sex": "F",
                "state": "",
                "subjectName": "Alice Smith"
            }
        ]
    }
}