1 Getting Started

The ClearTrial Web Services API is a simple and powerful web services interface into the ClearTrial software. It is a HTTP-based API that is technology and platform independent.

Requirements for working with the API

To use the ClearTrial Web Services API, the client must be able to issue HTTP GET, POST, PUT, and DELETE calls. The client can be Java, .NET, Perl, Python, or a command line curl call.

User Capabilities

To work with the ClearTrial Web Services API, you must be a licensed user who has been granted the additional role/capability "Can access WS-API" by the system administrator.

Note:

The Web Services capabilities are only available to licensed users. Please contact your clinical services manager or account manager for details on subscribing to the ClearTrial Web Services API.

Stateless API

The Web Services API that the ClearTrial software exposes is stateless. This means that each call is independent of the previous call, and the information conveyed by the client in the request must be sufficient for the server to understand and act upon the request.

Compression

To decrease network bandwidth usage, if the incoming HTTP request contains the Accept-Encoding HTTP header with gzip value, the ClearTrial software compresses the contents it returns.

Security

All communication with the ClearTrial Web Services API is encrypted and secured using HTTPS connections.

Authentication

The ClearTrial Web Services API supports the Basic Access Authentication scheme.

The ClearTrial Web Services API expects that the Authorization HTTP header has already been populated with the Base64 encoding of the username and password (as described in the IETF specification) when accessing the resources. The ClearTrial Web Services API will not challenge the user by sending a WWW-Authenticate HTTP header if it detects that the Authorization HTTP header is missing.

Every request must also contain the ClearTrial Customer ID in an HTTP header named customerCode.

Here is an example of authentication using the UNIX command line tool curl:

curl --user myLogin:myPassword --header"customerCode: myCustomerCode"  --get https://api.cleartrial.com/cleartrial-ws/plans/10802/siteInformation

ClearTrial Resources

The ClearTrial Web Services API exposes resources through distinct URLs and the HTTP method calls dictate the action that is required to be performed on the identified resource. ClearTrial resources include products (medical devices and drugs), studies, plans, portfolios, actuals, and other resources. The ClearTrial Web Services API refers to products as compounds.

Each resource may have zero to many sub-resources. Sub-resources make sense only within the context of the parent resource and, therefore, the sub-resource URLs use the parent resource URL as the base. Examples of resource and sub-resource URLs appear in subsequent chapters.

The ClearTrial Web Services API also supports reading and writing ClearTrial Track data in and out of the ClearTrial software. The resources supported for the Clear Trial Track application include sites, subjects, and monitoring.

Representations

Every resource has a representation. The representation can appear as XML or JSON, according to user preference. The user can set the Accept HTTP header in the request to either application/xml or application/json, respectively.

In the absence of the Accept header, the ClearTrial Web Services API returns the representation in JSON.

An example of an XML representation of a plan resource appears as follows:

<plan>
    <id>10801</id>
    <name>Baseline Locked Plan</name>
    <code>test</code>
    <createdBy>administrator</createdBy>
    <createdDate>15-Apr-2010</createdDate>
    <lastModifiedBy>administrator</lastModifiedBy>
    <lastModifiedDate>15-Apr-2010</lastModifiedDate>
    <planState>Draft</planState>
    <outsourcingOption>Combination</outsourcingOption>
    <startDate>01-Apr-2010</startDate>
    <preStudyStartDate>01-Jan-2010</preStudyStartDate>
    <defaultModelingCurrency>USD</defaultModelingCurrency>
    <drugHandlingType>Room Temperature</drugHandlingType>
    <radioLabeledDrug>false</radioLabeledDrug>
    <locationsUrl>/cleartrial-ws/plans/10801/locations</locationsUrl>
    <siteInformationUrl>/cleartrial-ws/plans/10801/siteInformation
    </siteInformationUrl>
    <siteApprovalScheduleUrl>/cleartrial-ws/plans/10801/siteApprovalSchedule
    </siteApprovalScheduleUrl>
    <dataUrl>/cleartrial-ws/plans/10801/data</dataUrl>
    <subjectUrl>/cleartrial-ws/plans/10801/subject</subjectUrl>
    <treatmentUrl>/cleartrial-ws/plans/10801/treatment</treatmentUrl>
    <monitoringInformationUrl>/cleartrial-ws/plans/1001/monitoringInformation
    </monitoringInformationUrl> 
    <monitoringScheduleUrl>/cleartrial-ws/plans/10801/monitoringSchedule
    </monitoringScheduleUrl>
    <serviceProviderUrl>/cleartrial-ws/plans/10801/serviceProvider
    </serviceProviderUrl>
    <laborUrl>/cleartrial-ws/plans/10801/labor</laborUrl>
    <laborMonthlyByMajorTaskUrl>/cleartrial-ws/plans/10801/
    labor?view=monthlyByMajorTask</laborMonthlyByMajorTaskUrl>
    <laborMonthlyByResourceUrl>/cleartrial-ws/plans/10801/
    labor?view=monthlyByResource</laborMonthlyByResourceUrl>
    <costUrl>/cleartrial-ws/plans/10801/cost</costUrl>
    <costMonthlyUrl>/cleartrial-ws/plans/10801/cost?view=monthly
    </costMonthlyUrl>
    <url>/cleartrial-ws/plans/10801</url>
</plan>

An example of a JSON representation appears as follows:

{
"id":"10801",
"name":"Baseline Locked Plan",
"code":"test",
""createdBy":"administrator",
"createdDate":"15-Apr-2010",
"lastModifiedBy":"administrator",
"lastModifiedDate":"15-Apr-2010",
"planState":"Draft",
"outsourcingOption":"Combination",
"startDate":"01-Apr-2010",
"preStudyStartDate":"01-Jan-2010",
"defaultModelingCurrency":"USD",
"drugHandlingType":"Room Temperature",
"radioLabeledDrug": false,
"locationsUrl":"/cleartrial-ws/plans/10801/locations",
"siteInformationUrl":"/cleartrial-ws/plans/10801/siteInformation",
"siteApprovalScheduleUrl":"/cleartrial-ws/plans/10801/siteApprovalSchedule",
"dataUrl":"/cleartrial-ws/plans/10801/data",
"subjectUrl":"/cleartrial-ws/plans/10801/subject",
"treatmentUrl":"/cleartrial-ws/plans/10801/treatment",
"monitoringInformationUrl":"/cleartrial-ws/plans/10801/monitoringInformation",
"monitoringScheduleUrl":"/cleartrial-ws/plans/10801/monitoringSchedule",
"serviceProviderUrl":"/cleartrial-ws/plans/10801/serviceProvider",
"laborUrl":"/cleartrial-ws/plans/10801/labor",
"laborMonthlyByMajorTaskUrl":"/cleartrial-ws/plans/labor?view=monthlyByMajorTask": 
"laborMonthlyByResourceUrl":"/cleartrial-ws/plans/labor?view=monthlyByResource",
"costUrl":"/cleartrial-ws/plans/10801/cost",
"costMonthlyUrl":"/cleartrial-ws/plans/cost?view=monthly",
"url":"/cleartrial-ws/plans/10801"
}

Every resource representation contains a URL property that indicates to the client the unique URL associated with that instance of the resource.

In the previous examples, <url>/cleartrial-ws/plans/10801</url> and "url": "/cleartrial-ws/plans/10801," in the XML and JSON representations, respectively, indicate that the plan resource whose plan ID is 10801 can always be found at that URL location.

The plan representation contains other URL properties such as locationsUrl, siteInformationUrl, siteApprovalScheduleUrl, and others. These are sub-resources under the plan resource and the URLs indicate the locations for that plan resource instance's sub-resources.

For example, the site locations for the plan resource whose ID is 10801 can be found at the URL, /cleartrial-ws/plans/10801/locations.

The curl Unix command is:

curl --user myLogin:myPassword --header"customerCode: myCustomerCode" --header"Accept: application/json" --get https://api.cleartrial.com/cleartrial-ws/plans/10801/locations

To obtain the XML representation, change the Accept header value in the previous command to:

"Accept:application/xml"

Some of the APIs also allow a client to add or update resources using the HTTP PUT or POST method. For example, a client can add a new compound or product into ClearTrial at the URL: /cleartrial-ws/compounds. Assuming the content is in the file postContent, the curl Unix command is:

cat postContent | curl --user myLogin:myPassword --header"customerCode: myCustomerCode" --header"Content-Type: application/json" --request PUT https://api.cleartrial.com/cleartrial-ws/compounds

To use the XML representation, change the Content-Type header value in the command above to:

"Accept:application/xml"

Error Codes

The following HTTP error codes may be returned for the reasons as follows:

400 - missing customerCode header

401 - wrong customerCode

401 - incorrect/missing credentials

403 - credentials provided do not have the necessary permissions required for access

404 - incorrect URL used

Detailed API Specifications

The following chapters describe the ClearTrial Web Services APIs, grouped by ClearTrial resources, and the ClearTrial Track API. In the URLs shown, values within braces {} are placeholders for entering the ID of a specific instance of the resource.

For example, in /cleartrial-ws/studies/{studyID}, the {studyID} is a placeholder for any study IDs identified in the <id> elements in the representation returned by the GET call to /cleartrial-ws/studies.

Each ClearTrial Web Services API specification includes the following information:

Purpose

Method: GET or PUT

The URL to which the call is made

Sample output in JSON for a late-stage study

Sample output in XML for a late-stage study

Sample output in JSON for a Phase I Healthy Volunteers study, if it differs from a late-stage study

Sample output in XML for a Phase I Healthy Volunteers study, if it differs from a late-stage study