TrialKit API

Owned by TK Support
Last updated: May 05, 2022 by TK Support
15 min read

Share or Open on Web

This article covers the TrialKit API, how it works, and many of the common endpoints available for integrating external applications with TrialKit’s wide range of functions. While the goal is to make any integration possible, this article is not a comprehensive list of methods. If you cannot find what you need here, please submit a request for additional parts of the system you may need to integrate with.

 

Overview

TrialKit is a cloud-based data collection and trial management system. A single sign-in can get you access to a host or hosts across multiple clouds, seamlessly. As a developer, you should have a thorough understanding of the process involved with switching hosts. Especially when those hosts exist on different clouds. This Overview will detail that process.

Table of Contents (TOC)

To manage the multiple clouds, which can exist anywhere, a central database exists called the Table of Contents (“TOC”). The TOC keeps track of:

  • All users across clouds in the system

  • All hosts across clouds in the system

  • Users by hosts across all clouds

The TOC has a table of servers that exist. Each server has an API URL for access. When you switch hosts, you should always query the TOC to get the API URL so that you can make the proper calls.

Default Hosts and Studies

The possibility of having access to multiple Hosts and Studies requires that you set the given host and study as the default for your user account prior to making calls to accomplish something on that study. By doing so, you make subsequent calls to query data from the host and study by authenticating. Once authenticated, the system pulls the current host and/or study when servicing calls. This restricts developers to only accessing data for the hosts and studies to which they belong.

To use the API on a host or study, you must set the host or study as the default first. If the API user only belongs to a single study, the default will always be the same.

Additionally, Hosts can exist on different servers which have different URLs. Based on the server where the user’s current default host exists, the corresponding URL must be used when calling the API. That URL can be retrieved when getting the current host described further below.

Gaining Access to the API

Because the API forces authentication for each call, the only way for a developer to be able to make calls, is by getting user credentials and a role to a target host. From within that host, you must also be given an access role to a given study. Once you have been given the proper credentials (Email / Password combination), you will use the creds to authenticate each call to the API. The data you can access will be restricted based on the role and its corresponding permissions granted by the Host and Study Administrator.

The Study Administrator can create your credentials and give you the proper access to the hosts and studies that you need to query.

Lastly, for security reasons, you will be restricted to specific calls and methods to which you have been granted access. This is controlled by a security key/token which is granted by Crucial Data Solutions to licensed API users based on the functions needed by each user.

 

API Basics

The CDS WebAPI follows the REST standard completely. Therefore, calls to the API are for the most part very simple. Gathering data to make the calls and retrieving data returned from the calls will be your biggest challenge.

This knowledge content is intended for experienced developers who have some experience with REST APIs and the system they will be using. The terms API, WebAPI and Web Service are used interchangeably throughout this help content.

It provides the necessary steps to do the following:

  • Authenticate

  • Make a standard Get Call

  • Make a standard Post Call

There is a call for every function within TrialKit. Every call does its own authentication by encoding the Email / Password of the TrialKit user and passing that encoded string to the web service call.

We highly recommend that you download the TrialKit app, sign in with your credentials and familiarize yourself with the system for a better understanding of the system structure and functions being accomplished through the API.

TrialKit Roles and Rights

By learning the system, you can see exactly how roles are created. Each role is granted access rights to Apps and functions within the various apps. There are over 100 different Apps that make up the TrialKit and TrialKit systems. The Host/Study Admin Users determine which user roles can access which Apps and App functions. For the most part, Admins should be granted access to everything, with the possible exception of the plethora of delete functions. Learning the Role Security system within TrialKit will greatly increase your ability to access the various data through the API with your current role or to create new apps and features and limit them to certain roles and rights.

Returned Data

All data returned by the web service comes in a standard Key/Value Dictionary. All modern languages use dictionaries to handle data and you should be at least familiar with how to access components within the dictionary. Much of the data returned by API calls is stored in arrays of dictionaries. Understanding key/value pairs is important.

Accessing Data

There are two call types; TOC and Host Web Service. Both are web services. Sometimes you must call the TOC, especially when changing hosts. The TOC will return to you the  URL of the Host Web Service. Then, all calls you make for that host and its corresponding studies, you will use the Host Web Service URL. 

Prior to making any web service calls, you must gather two pieces of information that you will  use in the header of your REST calls: 

  • E-Mail / Password combination. This is assigned to you by your study administrator. You can (and should) download TrialKit and Sign In with these credentials. 

  • From Access Key. The From Access Key is assigned to you by CDS. It is an email address that allows you access to the calls you will need to make. 


REST Error Conditions

It is of great importance that you understand there are two ways that the REST standard can report errors. There are standard web service errors such as 401 and 404. Those errors mean you probably have an error in the URL being used to call the web service.  

The second and most important error condition sends back a 200 code (success), but the return dictionary contains the key: "error". The value of the key is the actual error message. The call failed any time that the "error" key appears in the return dictionary. Your code should always check for an "error" key first on any 200 return condition. Here is a quick snippet of how Objective C  handles this condition: 

 

// Get data from the web service NSError *e = nil; id jsonObject = [NSJSONSerialization JSONObjectWithData: data options: NSJSONReadingMutableContainers error: &e]; NSDictionary *u = (NSDictionary *)jsonObject; [General stopActivity:self.aivc]; // Check for error here NSString *errTxt = [General getStringFromDict:u :@"error"]; if (![errTxt isEqual: @""]) { NSString *body = [NSString stringWithFormat:@"%@ %@. %@", NSLocalizedString(@"webservice_returns_error", @""), errTxt, NSLocalizedString(@"email_sent_to_CLSDS", @"")]; [General showAlert:NSLocalizedString(@"set_new_study_failed", @"") :body :NSLocalizedString(@"ok", @"") :self]; return; }

 

Passing Different Field Type Values

Date/time

The example assumes user preference is dd-mon-yyyy (4) hh:mi24 (2) 

Alpha characters in date are not case-sensitive

{  "fld_id": "99",  "fld_value": "18-Oct-2001 17:01",  "fld_name": "dateandtime"  } 

 

String

{ "fld_id": "99", "fld_value": "Hello World", "fld_name": "string_field"  }

 

Memo

 

Single Select/radio

fld_value_decode is an optional parameter

 

Number

Stored in DB as Double Precision floating-point numbers 

 

Check

fld_value_decode is an optional parameter 

 

Partial date

Assumes user preference is dd-mon-yyyy (4) 



Common Calls

The list below is the most commonly needed calls. Please contact support if there are any functions you need access to which are not published here.

Remember from the basics covered above, calls require a URL that depends on where a controller/method is being called. URLs that are always the same will be referenced below. For any that depend on the user’s server, it will be referenced in the following format:

<URL>/Controller/Method/Route

If POST call is being made, the parameters are passed in the body. Those will be detailed below based on the post call being described.

Sign In

TrialKit is a multi-cloud platform. Basically, that means that  TrialKit data is stored across clouds. In order to access that data, you must first Sign In. That gives you information about your user account, but also it tells you the server that your current host resides on. That server has a Host Web service URL and you will collect that and use it to access data from that host, including all study and patient data. 

Simply enter the TOC URL as a post.

POST

https://toc.clinicalstudio.com/api/toc/11

Next set the following headers similar to what you see: 

You should have been assigned an Access Key. That is an email address that is used to authenticate your developer account. That key should be used in the FROM header.

Next, click the SEND button to send your request to the server. You should receive a 200 code in return. The following is the documentation for the Sign-In method:

In your code, you will want to store this data. The server_webservice_url is of particular importance. You will use it to access all your study and patient data from the current host. All of the REST calls are made in a similar fashion. You just need to distinguish between a call to the  TOC and a call to the Host Webservice. 

Get a List of Hosts to which you belong

GET

https://toc.clinicalstudio.com/api/toc/9

If you will be accessing data across different hosts, then this method is very important. Prior to changing a host, you must know something about the host. Calling this method is very simple and straightforward: 


Get the Current Default Host and Study

GET

https://toc.clinicalstudio.com/api/toc/10

This will get the host and study the user is currently set on. It’s an important check to make if the API user belongs to multiple studies, to be sure subsequent calls made are being done in the intended study.

Set or Change Default Host

It is possible you may need to set another host as the default.

Most operations work on the default host and default study so setting the default host is very  important.

This is a very simple call. The list of hosts you belong to can be gathered from a separate call. To change a host, you must use one of those host IDs you belong to. The system will prevent setting a host that the calling user is not a part of.

POST

https://toc.clinicalstudio.com/api/toc/1

Body:

 

Get List of Studies for Default Host

GET

<URL>/study/12

All previous listed calls have called the TOC web service to gather information. Once the user has signed in and set the default host, a default study must be set. To do that a list of the studies is needed from the default host.

We must first capture the web service URL for the default host. This can be done in a variety of ways, but when you set the default host, this URL was returned. Depending on the cloud you are working on it will look something like this: 

https://webapi.clinicalstudio.com/api 

We will use this web service now to retrieve host, study, and patient information. 

The first step is to get a list of studies, this is another very simple operation. Remember it operates on the default host. We will be calling the study controller to get a list of studies that belong to the default host. The call should look something like this: 

https://webapi.clinicalstudio.com/api/study/12

Set a Default Study

POST

<URL>/user/2

Body:

 

This service returns nothing if it works. Like all other services, if it does not work it will return "error" as a key in the dictionary. Services do not have to return anything. The 200 status is enough for some services. 200 along with an empty dictionary means the call succeeded and you can move on. 

Get a List of Study Sites

GET

<URL>/site/1

Each study contains a list of sites that can contribute content to the study. That content is usually in the form of patient data across various sites which are entering data in the study. Users can belong to one or more sites depending on their role. Administrative users usually belong to all sites in the study. 

We want to get a list of all the sites to which we belong. We are going to call the site controller to accomplish this. 

Set a Default Site

POST

<URL>/site/9

Body:

 

Get a List of Site Subjects

GET
<URL>/subject/1/<site_id>

This is the first GET service where you are passing two parameters. The two parameters tell  REST how to route the call. Once routed the first parameter routes the call within the controller. In this case, you are saying route this call to the Subject Controller. From there, find the get procedure that requires 2 header parameters. Once there, check the first parameter for the route within the subject controller. In this case, get all subjects for the passed site. 

The site ID is obtained from another call.

By retrieving a list of subjects for any given site to which you belong, you are now ready to access the subject data.



Get All Records For a Subject

GET
/subject/3/<sub_id>/<form_id>

With the list of subjects previously retrieved, it is time to ask the web service to return all the completed records for a given subject. Optionally, you can pass a specific form_id and filter by just that form. If you do not want to filter by form, simply pass a -1. 

This call returns a list of records that belong to the sub_id that you passed.

Usually, the important factor being retrieved from this information is the trans_id of each record. With the trans_id, it will be possible to then get the data from that record next.

GET Form Data, Values, and Queries

GET

<URL>/form/11/<trans_id>

The trans_id was received in the prior call to get all subject records. Simply passing that to this method returns all of the data required to read a record.  

Records are dynamic in TrialKit. That means that forms are created by Study Builders on the fly. There are no hard-coded form layouts. In order to make sense of the data you actually need to parse the form data dictionary, which is returned in the method.

 

Get User Preferences

GET
<URL>/user/11

This is important to verify the correct date format is being passed later on when doing any data updates on date or time fields.

In order to send receive dates to the API, we must know the date and time format for our user account. This can all be hardcoded, but if you want to be to able freely change those formats, and still have your code work, you will need to retrieve those formats from the User Preferences.

Date Format options are listed below.

Pay particular attention to the ID column in the above tables. That ID is what the API will pass to you when retrieving the user preferences.

ID 

Format 

Display

1 

MM-DD-YYYY 

10-16-2013

2 

Mon-DD-YYYY 

Oct-16-2013

3 

DD-MM-YYYY 

16-10-2013

4 

DD-Mon-YYYY 

16-Oct-2013

5 

YYYY-MM-DD 

2013-16-10

Time Formats:

ID 

Format 

Display

1 

HH:MI AM 

02:00 pm

2 

HH24:MI 

14:00

 

Register a New Subject

POST

<URL>/form/16

When registering a new subject, you must complete the registration form. That form is created by the Study Builder and can be extremely simple or very complex. We generally encourage the registration process to be as simple as possible, usually collecting some date information, etc.

This example will show a registration form with only two fields.

All that is required by TrialKit is to have a date of registration. Any other field data depends on how the form was designed. The first date is known as the Registration Start Date and is used to calculate visit intervals and other items based on rules created by the study builder. For us, when registering a new subject, this is the only data that we need to pass.

All that has to be passed is the actual form data for the registration form.  Optionally, you can pass another key/value pair to override the system-generated Subject Profile ID. The Subject  Profile ID is used to identify a subject. If, when registering a  new subject, you want to override the Subject Profile ID, you can pass that in the body of the call as well. 

Here is a look at the body of the Post which is a JSON string: 

Notice the last key/value pair is the sub_profile_id. This tells TrialKit to override the system and use the value of this key as the Subject Profile ID. 

 

Add or update subject records

POST

<URL>/form/17

Creating a New Record

Body:

If updating an existing record, the trans_id is needed. This is obtained from the subject/3 call. The trans_id is the primary key for all subject visit/event records. For example, an Adverse Event form is considered a subject visit/event record and uses the trans_id as its primary key. That visit/event record is related to the subject by the sub_id. In addition, records can be scheduled,  unscheduled, or considered log forms. 

Updating an Existing Record

Body:

The only difference with updating a record is the trans_id being defined.

There are a few rules with scheduled and unscheduled visits; the most important is you can only have a single form completed for a single interval. That means in the baseline interval, you can only save a single inclusion/exclusion form. If you want to update that form, you must first retrieve that form's trans_id. Log forms can have multiple records as they are just stored longitudinally. However, if your study builder restricts log forms to a single record and you try and save multiple records, the API will return an error.

 

Getting Scheduled Visits and their Related Forms

GET

<URL>/subject/4/<sub_id>

Depending on what you are trying to accomplish, you may be to retrieve the scheduled visits for a given subject. Remember, the visit schedule for subjects within a study can differ based on the Scheduled Visit Cohort that is assigned to a particular subject. Fortunately, this is very easy  using the API.

This method retrieves the assigned cohort for the passed subject. It then goes and retrieves the  scheduled visits for that cohort/patient. In addition, for each schedule visit interval, it also  returns the list of forms and activities that have been assigned.

Get File Repository

GET

<URL>/study/17

The calling user’s role must be granted access to the file repository in order for this API to return any data. If the calling user does have access to the file repository, this call will return information for each file uploaded for the study for all sites. Below is a sample that shows the keys and values returned for each document.

Get a File from the repository

GET

<URL>/doc/3/<doc_id>

API users can download specific documents that have been uploaded during the study. When downloading a specific document from the file repository the TrialKit system will ensure the calling user has access to the particular file by checking the site/form/field rights. After the user’s access is authorized, the API will return the document in the body of the HTTP response object. The body in the API’s response will be the binary data that makes up the actual document. This data can be saved as JPG, PDF, or the specific type of the file that was requested. The Content-Disposition key of the returned HTTP response will contain the filename and will be set as follows: “attachment; filename=BaselineChestXray.png”

Downloading a Binary Object

GET
<URL>/image/3/<form_id>/<field_id>/<trans_id>/<row_pk>

Trialkit can collect many forms of binary data, including image, audio, av, pdf and more. Those  binary objects are stored by field. For example you may have a signature field, where a user  must sign a form. To download the actual image, you must call the image controller. 

The TrialKit API, will stream the data down to your call. The data being streamed is the actual  binary data that makes up the field object, such as a JPG file or PDF file. Any MIME type that  can be entered into the content-type header, can be streamed to your code. 

Getting Wearables Device data (HealthKit)

POST

<URL>/activity/5 with the body as follows:

Prerequisite: The study must be enabled by CDS for accessing wearable data.

 

To utilizing API calls or inquire about the many uncommonly used APIs, please reach out to the support desk.