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