ezyVet API
The ezyVet API is a powerful and flexible RESTful interface designed to seamlessly integrate with the ezyVet PIMS. Built with modern web standards, it leverages OAuth 2.0 Client Credentials grant for secure authentication, ensuring robust access control for your applications. The API accepts URL parameters and JSON-formatted requests, delivering responses in JSON format for easy parsing and integration.
This API enables developers to interact with a wide range of ezyVet resources, such as animal records, appointments, diagnostics, and more, allowing for automation and customization of veterinary workflows. Whether you're fetching data, creating records, or updating existing information, the ezyVet API provides a comprehensive set of endpoints to support your needs.
What you'll find 🔎
- A catalog of endpoints with query parameter and response details.
- Best practice documents to ensure you're building the best integration possible.
- Dedicated documentation for providers that specialize in Dx, PACS and ordering.
- Frequently asked questions and answers.
- Information on how to apply to use the API and what's involved in the process.
- OpenAPI specs for every section, in JSON and YAML, to download or import by URL.
Need more help? 💬
Find more info on our support page.
Check out our guides!
Authenticating
ezyVet uses a oauth2.0 style authentication model and utilizes bearer tokens.
Details on how to authenticate can be found here.
When and how often?
ezyVet API bearer tokens have a TTL of 12 hours; noted in the response body in epoch format in the expires_in field. An automated solution for refreshing tokens should be put in place to ensure a valid token is always stored.
json
{
"access_token": "token12345",
"token_type": "Bearer",
"expires_in": 1209600
}When an invalid token is used to make an API call, a 401 Unauthorized response will be given. This should be the indicator to generate a new token.
json
401 Unauthorized
{
"messages": [
{
"level": "error",
"type": "InvalidRequestException",
"text": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \"access token\" parameter.",
"fields": []
}
]
}INFO
We do not suggest nor recommend generating a new access token before every API call. This workflow has the potential to impact the API’s performance.
When generating a bearer token, ensure that all scopes associated with the integration record are provided in the HTTP request. This will allow the token to be used for all appropriate endpoints.
Errors
| Code | Name | Description |
|---|---|---|
| 400 | Bad Request | You have submitted an erroneous request. Check the URL, as well as all the input fields. |
| 401 | Unauthorized | Your request is not allowed. Check if your access token or client credential is valid. |
| 403 | Forbidden | The endpoint requested is either not allowed for you, or does not exist at all. |
| 405 | Method Not Allowed | The endpoint exists, but the HTTP method is not supported for it. |
| 422 | Unprocessable Entity | Your request itself is correct, but it fails one or more of our validation checks. Please see the error message in the response for details. |
| 500 | Internal Server Error | Oops, something's wrong on our end. 😦 Please check back later. |
Paging
On various results (mainly GET), you will notice the following under the meta[] property. These are used for item page navigation of the request.
| meta | Description |
|---|---|
items_page | Current page of the result. On requests, you can pass page to specify the page to be returned. (Default: 1) |
items_page_total | Total number of pages that the same request will return. |
items_page_size | Number of items per page. |
items_total | Total number of items |
Page size
The default page size is 10 and can be increased up to 200 for most endpoints through the use of the limit query parameter.
HTTP
GET /v2/contact?limit=200 HTTP/1.1
Host: api.trial.ezyvet.com
Authorization: Bearer tokenRequest Throttling
All endpoints are throttled at a certain number of requests per minute. This is to minimize the impact that API calls have on the performance of the system for users.
The throttle limits vary, depending on the endpoint and the data it provides, but most commonly is set to 60 calls per minute.
In addition to an endpoint specific rate limit there is also a global rate limit, which is by default set to 180 calls per database per Partner. This allows multiple endpoints to be called within the same rate limit period (minute), collectively up to the global limit.
If the number of calls made exceeds the limit in any rate limit period, the API will restrict further calls and return a 429 error message. One endpoint limit being reached will not restrict you from making calls to another that has not reached its own limit, while you remain within the global limit for that rate limit period.
An integration is identified by it’s UUID (partner_id) and is granted a rate limit for each ezyVet database. These limits are independent of each other meaning if the limit is reached on one database, the other database is not impacted.
INFO
If multiple instances of the same API Partner record (multiple sets of client credentials) are configured on one site that share a partner_id, they will share the rate limit.
Paying attention to the amount of calls an integration is making in a given throttling period is important as any calls that are made in excess of the limit are not accepted/processed by the API.
If a large number of excessive calls are made, it has the chance of impacting the performance of not just the API but the UI of the affected site as well. This will be directly noticed by the users of the software and may result in ezyVet staff disabling the API connection to preserve the integrity of the site.
INFO
Ensure to look out for the HTTP response headers described below.
| Header | Description |
|---|---|
| x-ratelimit-limit | The maximum number of requests that can be made within the current throttling period. |
| x-ratelimit-remaining | The number of requests remaining within the current throttling period. If this value is 30, then you have 30 requests remaining within the current throttling period. |
| x-ratelimit-reset | The cooldown or reset/throttling period. After x-ratelimit-reset seconds have passed, the x-ratelimit-remaining quantity will be reset to the x-ratelimit-limit amount. |
| x-item-limit-per-page | The maximum amount of records that can be requested per page, using the limit query parameter. |