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

Calls to the API can use HTTP Basic Authentication, or Token Authentication.

Basic Authentication

To authenticate using HTTP Basic Authentication, use the same credentials (username and password) as for normal logins in a web browser.

Token Authentication

The token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal “Token”, with whitespace separating the two strings. For example:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

For example, using cURL:

curl https://www.trialgrid.io/api/v2/users/ -H 'Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b'

An authentication token can be obtained by making an HTTP POST request to ‘api/v2/api-token-auth/’, providing your login credentials in JSON data in the POST request.

For example, using cURL:

curl --header "Content-Type: application/json" --data '{"username":"USER","password":"PASSWORD"}' --request POST https://www.trialgrid.io/api/v2/api-token-auth/

The API will return a JSON string containing the token, e.g.

{"token":"fa2ae7f1c766ddea1c8b4ff14773de33569d399b"}

An authentication token can be deleted by making an HTTP POST request to ‘api/v2/api-token-auth-delete/’, providing your login credentials in JSON data in the POST request.

For example, using cURL:

curl --header "Content-Type: application/json" --data '{"username":"USER","password":"PASSWORD"}' --request POST https://www.trialgrid.io/api/v2/api-token-auth-delete/

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 2 of the API:

https://beta.trialgrid.io/api/v2/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/v2/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"
    },
    ]
}

The current supported versions are:

• v1

• v2

beta and production sites

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

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

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

https://www.trialgrid.io/api/v2/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/v2/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/v2/drafts/999/checks/?limit=1000

and this request will return the next 1000 Edit Checks:

https://beta.trialgrid.io/api/v2/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/v2/drafts/999/checks/

The response will be like this:

{
    "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
        },
}

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_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
  

• 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
  

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

{
    "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/v2/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"}]
}