Application Programming Interface (API)

Castor EDC has an Application Programming Interface (API) that supports authentication and authorization of API calls through the industry standard OAuth2.  In this article you can learn about its authentication, documentation, and troubleshooting.

Authentication

Generate an API Client ID and Client Secret through your 'Account Settings' page:

With this client ID and secret you can request an access token, which you can use to access your Castor data. The access token is valid for 5 hours before it expires. 

Please note that the Client ID and Secret grant the same access to your data as your own username and password. Please treat them as such and do not hand them out to third parties, unless you want to allow them to have access to your data via your account.

Documentation & testing endpoints

All documentation for the API can be found on https://data.castoredc.com/api. If your study is on a different server, please make sure you use the right URL for the documentation:

Server	Documentation page
EU	data.castoredc.com/api
UK	uk.castoredc.com/api
US	us.castoredc.com/api
AU	au.castoredc.com/api

On the documentation page you can try out the endpoints:

1. Before you start, please make sure that you're a user in a study with the appropriate access rights.
2. Click on the green Authorize button on the right:
   
3. Enter your API credentials in the popup.
4. Click on one of the endpoints and click on "Try it out". 
5. Enter data for the parameters if applicable. 
   • See also this article about where you can find the right IDs.
   • See also this article about the differences between study forms, reports (instances), surveys (instances), and survey packages (instances).
6. Click "Execute". You will see the response below the endpoint.

The API is programmed to allows users using third party encryption providers like Trusted Reversible Encryption Service (TRES) to work with data on their premises. 

It also allows to filter the results based on the record id and the archive/non archive property.

Troubleshooting

If you run into errors that you cannot solve, check if they are listed in our API Troubleshooting article. If you have any other issues, please contact us at support@castoredc.com.