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/
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:
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=trueinclude_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=trueinclude_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=trueinclude_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=trueinclude_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=trueinclude_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=trueinclude_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=trueid__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,1025last_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:00Combined 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"}]
}