<a id="lists-filtering-and-object-detail"></a>
<a id="api-lists"></a>
# Lists, filtering and object detail

The API returns responses in JSON format.

<a id="lists"></a>
## Lists

This URL will return a list of Edit Checks in a Draft on the TrialGrid beta site:

```
https://beta.trialgrid.io/api/v2/drafts/999/checks/
```

The response will be like this:

```json
{
    "count": 3,
    "next": "http://beta.trialgrid.io/api/v2/drafts/999/checks/?limit=100&offset=100",
    "previous": null,
    "results": [
        {
            "id": 800,
            "CheckName": "CHECK01",
            "CheckActive": true
        },
        {
            "id": 801,
            "CheckName": "CHECK02",
            "CheckActive": true
        },
        {
            "id": 802,
            "CheckName": "CHECK03",
            "CheckActive": true
        },
}
```

<a id="list-query-parameters"></a>
<a id="api-list-query-parameters"></a>
## List query parameters

> **Note:** These options are not available in API v1.

The list output can be filtered and expanded using the following query parameters.

> - include_properties
>
>   > The include_properties query parameter will add any custom properties set for the objects in the list.
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?include_properties=true
>   > ```
>
> - include_labels
>
>   > The include_labels query parameter will add any labels added to the objects in the list.
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?include_labels=true
>   > ```
>
> - include_comments
>
>   > The include_comments query parameter will add any comments on the objects in the list.
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?include_comments=true
>   > ```
>
> - include_updated
>
>   > The include_update query parameter will add the last_updated, last_updated_by and fingerprint attributes for each object in the list.
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?include_updated=true
>   > ```
>
> - include_standards_compliance
>
>   > The include_standards_compliance query parameter will include the following attributes for objects which have standards compliance information (Forms, Edit Checks, Test Cases, Folders, Data and Unit Dictionaries and Custom Functions):
>   >
>   > > - compliance_state : One of MATCH, ALLOWED_CHANGES, DIFFERENT, NOT_APPLICABLE, CALCULATING or NOT_FOUND
>   > > - state_count_unexplained : Count of unexplained differences for the object or its chid objects (e.g. Fields of the Forms)
>   > > - state_count_approval_requested : Count of differences where approval has been requested for the difference but not yet approved/conditionally approved or denied by a Standards Manager.
>   > > - state_count_conditionally_approved : Count of differences which have been Conditionally Approved by a Standards Manager
>   > > - state_count_approved : Count of differences which have been approved by a Standards Manager
>   > > - state_count_denied : Count of changes which have been denied by a Standards Manager
>   > > - state_count_rules_passed : Count of Differences which are allowed by Standard Rules
>   > > - state_count_allowed_changes : Count of allowed changes for Forms and Data Dictionaries which have "allowed change" settings
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/folders/?include_standards_compliance=true
>   > ```
>
> - include_detail
>
>   > The include_detail query parameter will add all the attributes for each object in the list, excluding properties, labels, comments or updated.
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?include_detail=true
>   > ```
>
> - include_all
>
>   > The include_all query parameter will add all the attributes for each object in the list, including properties, labels, comments and updated.
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?include_all=true
>   > ```
>
> - id__in
>
>   > The id__in query parameter should be provided with a comma separated list of the TrialGrid object ids and will return the list of these objects (if they exist).
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?id_in=1023,1024,1025
>   > ```
>
> - label__in
>
>   > The label__in query parameter applies to the drafts list (`/api/v2/drafts/`) and should be provided with a comma separated list of label names. The list is filtered to drafts which have at least one of the named labels assigned. Soft-deleted labels are ignored.
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/?label__in=Ready,Final
>   > ```
>
> - last_updated__gt
>
>   > The last_updated__gt query parameter filters the list to objects which have a last_updated date/time after the provided value. The value must include a time and must be in ISO8601 format. The time zone for the request and the returned last_updated values is UTC.
>   >
>   > Examples:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?last_updated__gt=2021-10-01T19:12:30
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?last_updated__gt=2021-10-01T00:00:00
>   > ```
>
> - Combined query parameters
>
>   > The above query parameters may be combined.
>   >
>   > Example:
>   >
>   > ```
>   > https://beta.trialgrid.io/api/v2/drafts/999/checks?id_in=1023,1024,1025&include_detail=true
>   > ```

<a id="object-details"></a>
## Object Details

Details for an Edit Check can be retrieved with a URL like this:

```
https://beta.trialgrid.io/api/v2/drafts/999/checks/800
```

```json
{
    "id": 800,
    "CheckName": "AE001",
    "CheckActive": true,
    "BypassDuringMigration": true,
    "cql": "*.AE.AESTDAT > *.AE.AEENDAT",
    "text_description": "If in Form Adverse Events   \nField Start Date  is greater than  Field End Date \nthen: Open Query \" End Date is before Start Date. Please correct. \" on Field End Date to Marking group \" Site from System \" \n",
    "check_steps": [
        {
            "StepOrdinal": 1,
            "CheckFunction": "",
            "StaticValue": "",
            "DataFormat": "StandardValue",
            "VariableOID": "AESTDAT",
            "Folder": null,
            "Form": "AE",
            "Field": "AESTDAT",
            "RecordPosition": null,
            "CustomFunction": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "FormRepeatNumber": null,
            "FolderRepeatNumber": null
        },
        {
            "StepOrdinal": 2,
            "CheckFunction": "",
            "StaticValue": "",
            "DataFormat": "StandardValue",
            "VariableOID": "AEENDAT",
            "Folder": null,
            "Form": "AE",
            "Field": "AEENDAT",
            "RecordPosition": null,
            "CustomFunction": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "FormRepeatNumber": null,
            "FolderRepeatNumber": null
        },
        {
            "StepOrdinal": 3,
            "CheckFunction": "IsGreaterThan",
            "StaticValue": "",
            "DataFormat": "",
            "VariableOID": "",
            "Folder": null,
            "Form": null,
            "Field": null,
            "RecordPosition": null,
            "CustomFunction": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "FormRepeatNumber": null,
            "FolderRepeatNumber": null
        }
    ],
    "check_actions": [
        {
            "ActionType": "OpenQuery",
            "ActionString": "End Date is before Start Date. Please correct.",
            "ActionOptions": "Site from System",
            "ActionScript": "",
            "VariableOID": "AEENDAT",
            "Folder": null,
            "Form": "AE",
            "Field": "AEENDAT",
            "RecordPosition": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "PageRepeatNumber": null,
            "InstanceRepeatNumber": null
        }
    ]
}
```

<a id="edit-check-step-comments"></a>
## Edit Check Step Comments

Edit Check Step Comments (see [Quickedit for Edit Checks](../quickedit_checks.html.md#quickedit-checks)) can be retrieved using the `include_check_step_comments` querystring parameter.

```
https://beta.trialgrid.io/api/v2/drafts/999/checks/800?include_check_step_comments=true
```

```json
{
    "id": 800,
    "CheckName": "AE001",
    "CheckActive": true,
    "BypassDuringMigration": true,
    "cql": "*.AE.AESTDAT > *.AE.AEENDAT",
    "text_description": "If in Form Adverse Events   \nField Start Date  is greater than  Field End Date \nthen: Open Query \" End Date is before Start Date. Please correct. \" on Field End Date to Marking group \" Site from System \" \n",
    "check_steps": [
        {
            "StepOrdinal": 1,
            "CheckFunction": "",
            "StaticValue": "",
            "DataFormat": "StandardValue",
            "VariableOID": "AESTDAT",
            "Folder": null,
            "Form": "AE",
            "Field": "AESTDAT",
            "RecordPosition": null,
            "CustomFunction": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "FormRepeatNumber": null,
            "FolderRepeatNumber": null
            "StepComment": "Optional",
        },
        {
            "StepOrdinal": 2,
            "CheckFunction": "",
            "StaticValue": "",
            "DataFormat": "StandardValue",
            "VariableOID": "AEENDAT",
            "Folder": null,
            "Form": "AE",
            "Field": "AEENDAT",
            "RecordPosition": null,
            "CustomFunction": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "FormRepeatNumber": null,
            "FolderRepeatNumber": null
            "StepComment": "",
        },
        {
            "StepOrdinal": 3,
            "CheckFunction": "IsGreaterThan",
            "StaticValue": "",
            "DataFormat": "",
            "VariableOID": "",
            "Folder": null,
            "Form": null,
            "Field": null,
            "RecordPosition": null,
            "CustomFunction": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "FormRepeatNumber": null,
            "FolderRepeatNumber": null
            "StepComment": "",
        }
    ],
    "check_actions": [
        {
            "ActionType": "OpenQuery",
            "ActionString": "End Date is before Start Date. Please correct.",
            "ActionOptions": "Site from System",
            "ActionScript": "",
            "VariableOID": "AEENDAT",
            "Folder": null,
            "Form": "AE",
            "Field": "AEENDAT",
            "RecordPosition": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "PageRepeatNumber": null,
            "InstanceRepeatNumber": null
        }
    ]
}
```

<a id="object-details-with-additional-metadata"></a>
## Object Details with additional Metadata

Additional metadata, including [Labels](../urls/labels.html.md#labels), Comments and [Custom Properties (Metadata)](../urls/properties.html.md#properties), can be retrieved with the `metadata` suffix in the URL Path:

```
https://beta.trialgrid.io/api/v2/drafts/999/checks/800/metadata
```

```json
{
    "id": 800,
    "CheckName": "AE001",
    "CheckActive": true,
    "BypassDuringMigration": true,
    "cql": "*.AE.AESTDAT > *.AE.AEENDAT",
    "text_description": "If in Form Adverse Events   \nField Start Date  is greater than  Field End Date \nthen: Open Query \" End Date is before Start Date. Please correct. \" on Field End Date to Marking group \" Site from System \" \n",
    "check_steps": [
        {
            "StepOrdinal": 1,
            "CheckFunction": "",
            "StaticValue": "",
            "DataFormat": "StandardValue",
            "VariableOID": "AESTDAT",
            "Folder": null,
            "Form": "AE",
            "Field": "AESTDAT",
            "RecordPosition": null,
            "CustomFunction": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "FormRepeatNumber": null,
            "FolderRepeatNumber": null
        },
        {
            "StepOrdinal": 2,
            "CheckFunction": "",
            "StaticValue": "",
            "DataFormat": "StandardValue",
            "VariableOID": "AEENDAT",
            "Folder": null,
            "Form": "AE",
            "Field": "AEENDAT",
            "RecordPosition": null,
            "CustomFunction": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "FormRepeatNumber": null,
            "FolderRepeatNumber": null
        },
        {
            "StepOrdinal": 3,
            "CheckFunction": "IsGreaterThan",
            "StaticValue": "",
            "DataFormat": "",
            "VariableOID": "",
            "Folder": null,
            "Form": null,
            "Field": null,
            "RecordPosition": null,
            "CustomFunction": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "FormRepeatNumber": null,
            "FolderRepeatNumber": null
        }
    ],
    "check_actions": [
        {
            "ActionType": "OpenQuery",
            "ActionString": "End Date is before Start Date. Please correct.",
            "ActionOptions": "Site from System",
            "ActionScript": "",
            "VariableOID": "AEENDAT",
            "Folder": null,
            "Form": "AE",
            "Field": "AEENDAT",
            "RecordPosition": null,
            "LogicalRecordPosition": "",
            "Scope": "",
            "OrderBy": "",
            "PageRepeatNumber": null,
            "InstanceRepeatNumber": null
        }
    ],
    "fingerprint": "e1fe6aa020ea3144e308a7ba31ad1be1",
    "last_updated": null,
    "last_updated_by": null,
    "labels": [{"label", "Approved"}],
    "comments": [],
    "properties": [{"property": "Description of logic", "value": "Start date should be after end date"}]
}
```
