Search and list data subjects.

GET /v1/subjects?query

The query is a list of the following options:

The unique ID for the subject. If this is specified, at most one matching subject will be returned. ID is case sensitive.
This searches for a text in any one of the text fields. The text search is performed on individual terms included in the text parameter. To search for a phrase, use double-quotes, such as "example phrase". You can prepend a "-" character to exclude a term: "shop -coffee" will return records containing "shop" but not "coffee".
Data subject type. If omited, user is assumed.
The 0-based offset in the result set. If not given, 0 is assumed.
Maximum number of subjects to return in one API call. If not given, 100 is assumed. If larger than 200, it is truncated to 200.
This searches for a case sensitive match for a text field field.
This searches for a case-insensitive regular expression search for a text field field. ConsentGrid uses Perl Compatible Regular Expressions.
This searches for a numeric value in the field.
This searches for a true or false value in the field

The search parameter type must match the field type in the database. For instance, the following document will not match the query boolean.field=true, but will match string.field="true":


Nested fields can be accessed using the dot "." notation:

  "address": {
    "city": "anycity"

You can search for


200 Ok
  "total": 120,
  "subjects": [
      "id": {
        "type": "user",
        "id": "123abc"
      "version": 3,
      "versionTime": "2019-01-02T15:04:05Z07:00",
      "by": {
        "type": "user",
        "id": "def821"
      "data": {
        ... // Subject data

The version gives the current version number of the subject record. A version number of 3 means there are two older versions of the same subject record.

The total field gives the total number of matching records, regardless of the number requested.

400 Bad Request

Malformed request, invalid value, etc. The return value is a JSON error object containing diagnostic information.

403 Forbidden

The authenticated key does not have the privileges for this operation. The return value is a JSON error object containing diagnostic information.