TrialGrid API

TrialGrid provides a REST API to read CRF Draft objects. The API for draft objects is read-only, creating and updating objects via the API is not currently supported. The API for users includes endpoints for deactivating users, assigning users to project roles and removing project roles from users.

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

Note that this documentation can be used with both Username/Password authentication (the default) or with Token authentication. To use Token Authentication click the authorize button at the top right of the page and enter "Token XXXX" where XXXX is your API token in the dialog which appears:

Token authentication with swagger API

Subsequent requests will submit the authentication header. The token is forgotten when the page is refreshed.

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.

Important

The browseable API allows only Username/Password authentication. It cannot be used by users who are logged in via Single Sign on or by API Token Authentication. Use Swagger API documentation to explore the API with API Token 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_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
    
  • 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
        }
    ]
}

Edit Check Step Comments

Edit Check Step Comments (see Quickedit for Edit 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
{
    "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
        }
    ]
}

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