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/

Pagination¶

Requests to view lists of objects will paginate the results, with a default page size of 100.

This request will return the first 100 Edit Checks within the Draft with ID 999:

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

Pagination can be modified using query parameters ‘limit’ and ‘offset’.

This request will return the first 1000 Edit Checks with a Draft:

https://beta.trialgrid.io/api/v1/drafts/999/checks/?limit=1000

and this request will return the next 1000 Edit Checks:

https://beta.trialgrid.io/api/v1/drafts/999/checks/?limit=1000&offset=1000

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"}]
}