Summary

Certain product features and workflows are supported through the use of APIs. ClinSpark contains both private and partner API types. We define Private APIs in support of specific features and integrations with external systems such as SendGrid and Verified Clinical Trials. These also support proprietary functions of the system designed through use of the Agent and SparkPlug. We don’t expose private APIs or functions for customers to use.

Partner APIs however do exist to support use cases and features which are intended to be used by our customers. They are only accessible to customers of the product and are not available for public use. Currently, they are scoped for two purposes:

1. Integration with a customer recruitment website

2. Programmatic execution and retrieval of reports.

IQVIA can offer suggestions for how to use these APIs, however we cannot support or assist with implementation and ongoing support of customer-specific mechanisms that rely on them.

Costs associated with using APIs

APIs are enabled out-of-the-box. However, there may be a cost associated with the use of certain APIs.

The Recruit API may be disabled if not required.

Learning API Functions

Each of the API documentation pages contain information covering the scope and purpose of each interface. Additionally, there is an embedded Swagger UI client on the page with the purpose of allowing customers a simple interactive way to try out certain functions and learn how the API can be used. This video provides a quick demonstration on how to use the embedded functions.

We encourage customers to try and learn about API invocations with the Swagger UI client on this documentation site. Once you have successfully invoked the API with this client, you will find that it provides client bindings and command line invocation patterns that will work directly for integrations or other API clients/tooling.

For support requests, we ask similarly that customers first explore and troubleshoot using the Swagger client and include results of testing when reaching out via service desk.

Prerequisites for use

In order to use the interactive Swagger UI, you need the following:

1. A ClinSpark user account on the instance/environment used (‘server’)

2. The user account must have the api Role Action in one of their assigned Roles

3. In ClinSpark version 23.3 and greater, the user account must be setup with at least one of the supported authentication schemes (see below)

Supported Authentication Schemes

ClinSpark supports Basic HTTP (basic auth) and Bearer HTTP (token) authentication schemes.

Bearer HTTP tokens were introduced in version 23.3. Both auth schemes can be applied and used on API accounts.

Basic HTTP

All versions of ClinSpark support Basic HTTP Authentication via username and password. Starting in version 23.3, use of basic auth is supported with a specific account setting.

Within the Administration > Users component, edit an account intended for API use.

Open

Within the Update User modal, select the setting to enable basic auth:

Open

Available in ClinSpark 23.3 and greater

Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password. For example, to authorize as demo / p@55w0rd the client would send:

Bearer HTTP Tokens

ClinSpark versions 23.3 and greater support Bearer HTTP Authentication.

API tokens are generated and managed with ClinSpark user accounts for this purpose. These features are accessed in the Administration > Users component.

Multiple API tokens can be setup per account.

Supporting use of these features are specific Role Actions that allow users to view and manage tokens on accounts.

Role Actions | Administration Users View API Tokens

Role Actions | Administration Users Manage API Tokens

User Account Permissions

A specific API role action must be assigned to a user account in ClinSpark to use the API. For most use cases, these are typically accounts that facilitate workflows via ClinSpark web services. Integration applications that use specific ‘system’ accounts in ClinSpark must also be configured with this role action.

An example of how these API permissions apply to Recruitment website integrations can be reviewed in this article: Recruitment Website Integration | Granting the Website Integrators Appropriate Access

Other than the assigned role action and intended use, there are no unique properties of accounts used for API invocation.

Credential Management

Customers are expected to manage all user account credentials intended for API use.

We strongly suggest customers follow security best practices by assigning highly complex passwords (up to 255 characters) to the accounts and rotating them regularly. More information about ClinSpark user account management can be viewed in this article: User Management

Customers are encouraged to create and manage multiple API users if they decide to adhere to a strict credential management practice. Additionally, the creation and management of multiple bearer auth tokens set with expiry dates. This is our recommendation, so customers can properly process leavers/joiners with their own service account credentials, instead of having a pool of team members using shared credentials for singular service accounts.

Performance and Limitations

ClinSpark APIs were designed to allow customers to be reliant on them for common study recruitment and operational workflows. Some of those needs may be related to time sensitive tasks. Invoking endpoints programmatically may exceed the normal limitations imposed through using the user interface.

There are no request limits enforced or network throttling in place for API calls. However, this is an area under evaluation by the product team as more of our customers use the APIs; limits may be imposed in future.

To a certain extent, the performance of the APIs are based on the functions used. For example, the Report API allows for specifying one or more parameters as part of the request, which can influence the output to a specific set of subjects or timepoints in a study. Requests for fewer data points will result in a quicker retrieval of results. Additional performance considerations using the Report API can reviewed here: Report API | Performance

There may be additional limitations or performance implications to consider with a high volume of API requests. Customers are encouraged to reach out to IQVIA support teams on this topic to discuss and determine if there are performance risks associated with intended use.