OpenClinica has a highly capable RESTful web services API that enables you to interchange data programmatically with other systems, as well as carry out bulk actions such as importing data, scheduling events, or creating study participants.

The following pages are designed to help you understand how to use this API. We also provide an API toolset, called Swagger, that enables you to better understand and interact with various API endpoints.

To Access the Swagger Interface for your OpenClinica Domain:

  1. Click the User menu.
  2. Select Administration.
  3. Select Web Services Information.

API users of OpenClinica will need an authentication token in order to access the API endpoints.

To Obtain an Authentication Token Call the Following Endpoint:

URL:

POST to https://{subdomain}.build.openclinica.io/user-service/api/oauth/token replacing the {subdomain} with your instance subdomain.

For example: https://xyz.build.openclinica.io/user-service/api/oauth/token

Request Header:

  • Content-Type: application/json

Request Body:

{
	"username":" ",
	"password":" "
}

Response Body:

Response body will contain the authentication token.

Supply this Authentication Token in the Authorization Header as a Bearer Token When Accessing Other Endpoints:

Authorization: Bearer “authentication token“;

Important Note:

The rate limit for authentication token retrieval is 2 calls per minute per IP address.

Authentication tokens are valid for 4 hours. To avoid unnecessary load on the system, tokens should be reused and not refreshed until the expiration is approaching. When tokens are needed for multiple processes, initial retrieval of the tokens should be staggered so that the rate limit is not exceeded when the process is started.

Excessive calls to the authentication API will be blocked with a 429 status code. If this occurs, your script should retry a short time later (for example, wait 30 seconds or 1 minute and then retry). The aforementioned guidelines will ensure that the rate limit on retrieving tokens is not exceeded.

For Information on APIs, See the Following Sections: