TrialGrid API

TrialGrid provides a REST API to read CRF Draft objects. The API is read-only, creating and updating objects via the API is not currently supported.

Authentication

The TrialGrid API uses HTTP Basic Authentication, using the same credentials (username and password) as for normal logins in a web browser.

Authorization

Access to Drafts via the API is controlled by the same permissions as the main TrialGrid application. Drafts and Drafts objects can be retrieved by the API if the user account has access to view the Project.

Versioning

The API is versioned; the version number must be included in the API URLs.

For example, to retrieve the list of Drafts using version 1 of the API:

https://beta.trialgrid.io/api/v1/drafts/

The list of Drafts will be returned in JSON format and includes the Draft ID which will be needed in requests for other Draft objects:

{
"count": 3,
"next": "http://beta.trialgrid.io/api/v1/drafts/",
"previous": null,
"results": [
    {
        "id": 999,
        "DraftName": "001 DRAFT",
        "Project": "Project 1"
    },
    {
        "id": 2130,
        "DraftName": "Draft 2",
        "Project": "Project 1"
    },
    {
        "id": 2404,
        "DraftName": "v0.1",
        "Project": "Test Project"
    },
    ]
}

beta and production sites

Requests to TrialGrid beta should have a domain of beta.trialgrid.io

https://beta.trialgrid.io/api/v1/drafts/

Requests to TrialGrid production should have a domain of www.trialgrid.io

https://www.trialgrid.io/api/v1/drafts/

Swagger documentation

Full details of the API are available in the Swagger format including an OpenAPI schema specification

Browseable API

The API can be accessed and viewed in a web browser by navigating to a valid API URL. The web browser will prompt for the username and password to be used for authentication.

Format

The API returns responses in JSON format.

Lists

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

https://beta.trialgrid.io/api/v1/drafts/999/checks/

The response will be like this:

{
    "count": 3,
    "next": "http://beta.trialgrid.io/api/v1/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
        },
}

Object Details

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

https://beta.trialgrid.io/api/v1/drafts/999/checks/800
{
    "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
        }
    ]
}

Object Details with additional Metadata

Additional metadata, including Labels, Comments and Custom Properties (Metadata), can be retrieved with the ‘metadata’ suffix in the URL Path:

https://beta.trialgrid.io/api/v1/drafts/999/checks/800/metadata
{
    "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"}]
}