Cortex API
Search…
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.

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
Response
1
{
2
"id": 1,
3
"jsonrpc": "2.0",
4
"method": "querySubjects",
5
"params": {
6
"cortexToken": "xxx",
7
"query": {
8
"dateOfBirth": {
9
"from": "1979-01-01",
10
"to": "1980-12-31"
11
},
12
"sex": "F"
13
},
14
"orderBy": [
15
{"subjectName": "ASC"}
16
],
17
"offset": 0,
18
"limit": 10
19
}
20
}
Copied!
1
{
2
"id": 1,
3
"jsonrpc": "2.0",
4
"result": {
5
"count": 1,
6
"limit": 10,
7
"offset": 0,
8
"subjects": [
9
{
10
"attributes": [
11
{
12
"name": "Handedness",
13
"value": "Left"
14
},
15
{
16
"name": "Education",
17
"value": "Master's degree"
18
}
19
],
20
"city": "London",
21
"countryCode": "GB",
22
"countryName": "",
23
"dateOfBirth": "1980-12-25",
24
"experimentsCount": 0,
25
"modifiedDatetime": "2019-07-01T11:23:11.644+07:00",
26
"sex": "F",
27
"state": "",
28
"subjectName": "Alice Smith"
29
}
30
]
31
}
32
}
Copied!