General API Information
Base URL
Note that the documented URLs for all endpoints are preceded by a base URL, which is often implicit in the documentation.
For the sandbox environment (lab-sandbox.ovation.io), always start with https://lab-services-sandbox.ovation.io/api/v3
For the production environment (lab.ovation.io), always start with https://lab-services.ovation.io/api/v3
Authentication
Each call requires a Bearer token to be sent in the HTTP Authorization header.
For this, you need an "API key," which is generated in user settings in the application. (Select the User dropdown on top right of page and navigate to Settings and then to Security. From there, you can add an API key.)
API keys are specific to the environment. Create separate ones for use in sandbox and production.
The Bearer token is the API key preceded by the word "Bearer".
Failure to provide a valid API key will result in a 401 error from the endpoint.
Authorization
The API enforces the same permissions as the user interface as described in the Permissions Detail article. The permissions that apply are the ones held by the user that is associated with the API key that is passed as the Bearer token.
Conversion of JSON keys
JSON payloads that contain keys that are in PascalCase or camelCase will be converted, before processing, to snake_case. For example: KeyName and keyName will all be treated as if you had instead provided key_name. Some APIs may further translate these snake_case keys to some other format. See individual API documentation to see a description of any additional transformation.
Status Codes
Ovation's API returns status codes that follow the HTTP standard. Here are some of the codes returned:
| Code | Meaning |
| 200 | Success |
| 201 | Success (in the case that an entity is created by the request) |
| 401 | Authentication failed Possible causes:
|
| 404 | "Not found" In addition to the case where the endpoint is literally not available (consider a spelling error in your request), 404 is also returned when the user account does not have access to a relevant entity. For example, when attempting to GET a requisition with an API key linked to an account that does not have permission to access that requisition, the API will return a 404. 404 rather than 403 in this case is preferred for security purposes -- the API should not educate the caller as to which entities do and do not exist. |
| 406 | The request failed a requirement of the API, such as a missing required field or providing inconsistent values. The response message should indicate what the error is. 422 may sometimes be used instead. |
| 422 | This indicates that something is wrong with the request, often that the JSON is invalid. 422 may also be used in lieu of 406. |
| 429 | Too many requests were made too quickly so this one was rejected ("rate limited"). |