Castor CDMS 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 User 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:
- Before you start, please make sure that you're a user in a study with the appropriate access rights.
- Click on the green Authorize button on the right:
- Enter your API credentials in the pop-up.
- Click on one of the endpoints and click on "Try it out".
- Enter data for the parameters if applicable.
- See article: Where can I find IDs for the study/field/repeating data instance/... for the API? about where you can find the right IDs.
- See article: Parameters used in the API about the differences between study forms, repeating data (instances), surveys (instances), and survey packages (instances).
- 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 participant 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.
Also, please consider reviewing the API changelog for further reference on the recent changes.