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.

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.

Field Comparators

Unless otherwise specified, each field from the params of GET requests will accept multiple comparators in URL-encoded JSON. The following comparators are supported:

Comparator	Arithmetic	String	Remarks
Less than	<	lt	-
Less than or equal	<=	lte	-
Equal	=	eq	-
Greater than or equal	>=	gte	-
Greater than	>	gt	-
Not equal	-	neq	-
Like	-	like	String fields only
In	-	in	Similar `Equal`, except that it tries to find at least one match against many.

Examples

An API call to fetch Appointments that were created or modified after 1729455014 (epoch time).

cURL

curl    --location 'https://apiv2.trial.ezyvet.com/v2/appointment?modified_at={%22gte%22%3A1729455014}' \
        --header 'Authorization: ••••••'

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: apiv2.trial.ezyvet.com
Authorization: Bearer token

Large initial syncing

Often there is a need to pull a large number of records from a database as part of an initial load/sync. Due to the way the ezyVet API is built, navigating through thousands of pages can cause extensive load, resulting in a long response time. By reducing the context of the search, this can be mitigated.

It's recommended to partition the sync by following the below steps:

Using the active, id and limit query parameters, pull a certain number of records into context and enlargen the page size by using the gt and lt field comparators.

E.g. Fetch all active contact records where the ID is greater than 0 and less than 1001 and make the page size 200.

HTTP

GET /v2/contact?id={"gt":0, "lt":1001}&active=true&limit=200 HTTP/1.1
Host: apiv2.trial.ezyvet.com
Authorization: Bearer token

With only 1000 objects to parse and 200 objects appearring per page, only 5 pages need to be loaded. By using the page query parameter, we can navigate the data easily and efficiently.

HTTP

GET /v2/contact?id={"gt":0, "lt":1001}&active=true&limit=200&page=1 HTTP/1.1
Host: apiv2.trial.ezyvet.com
Authorization: Bearer token

Once the data from all 5 pages have been loaded, the process can be incremented based on the ID.

HTTP

GET /v2/contact?id={"gt":1000, "lt":2001}&active=true&limit=200&page=1 HTTP/1.1
Host: apiv2.trial.ezyvet.com
Authorization: Bearer token

Questions

Some API GET endpoints support Questions.

Questions return results from complex queries about a resource. For example, the Product question stocklevel will return various Product stock level numbers, such as total stock, stock allocated to invoices and so on.

WARNING

It's recommended to use the /inventory/v1/products endpoint to retrieve inventory/batch tracked products and their corrosponding inventory balances.

Request 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.

v1.0

API Endpoints

Download OpenAPI Document

The API accepts URL params and JSON-formatted requests, and returns JSON-formatted responses.

Authentication

Authenticate with the ezyVet API

Operations

POST/v1/oauth/access_token

Deprecated

Fetch a JWT bearer token

POST

/v1/oauth/access_token

It's recommended to use the V2 authentication endpoint

Request Body

application/json

JSON

{

"partner_id": "string",

"client_id": "string",

"client_secret": "string",

"grant_type": "client_credentials",

"scope": "string",

"site_uid": "string"

}

Responses

A JSON object containing the access token details.

Content-Type

application/json

JSON

{

"access_token": "string",

"token_type": "string",

"expires_in": 0

}

POST

/v1/oauth/access_token

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

Authentication V2

Authenticate with the ezyVet API

Operations

POST/oauth/token

Fetch a JWT bearer token

POST

/oauth/token

Generates a valid access token, given client credentials. Access tokens have an 12-hour TTL.

Request Body

application/json

JSON

{

"partner_id": "string",

"client_id": "string",

"client_secret": "string",

"grant_type": "client_credentials",

"scope": "string",

"site_uid": "string"

}

Responses

A JSON object containing the access token details.

Content-Type

application/json

JSON

{

"access_token": "string",

"token_type": "string",

"expires_in": 0

}

POST

/oauth/token

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

v1.0

System Admin

Download OpenAPI Document

This portion of the API provides endpoints for system administration

Servers

https://api.ezyvet.comezyVet production environment

https://api.trial.ezyvet.comezyVet trial environment

Attachment

Operations

GET/v1/attachment POST/v1/attachment GET/v1/attachment/download/{id}DELETE/v1/attachment/{id}PATCH/v1/attachment/{id}

Fetch an Attachment

GET

/v1/attachment

Authorizations

bearerAuth

clientCredentials Flow

Token URL"https://apiv2.ezyvet.com/oauth/token"

Scopes:

Parameters

Query Parameters

The ID number used by the system to uniquely identify an Attachment.

Typestring

active

If true, the Attachment is active and usable in ezyVet.

Typeboolean

created_at

The epoch time when the Attachment was created.

Typestring

modified_at

The epoch time when the Attachment was last modified.

Typestring

file_id

The ID number of the File linked to the Attachment.

Typestring

file_download_url

The URL of the file that if you get request will download the file.

Typestring

record_type

The record type the Attachment is for. E.g. Animal, Contact, Consult.

Typestring

record_id

The ID number of the record the Attachment is linked to.

Typestring

mime_type

Multipurpose Internet Mail Extension type. Identifies the format of the Attachment.

Typestring

name

The Attachment filename.

Typestring

primary_image

If true, the Attachment is the primary image for the linked record.

Typeboolean

notes

Notes that are related to the Attachment.

Typestring

Responses

A successful response

Content-Type

application/json

JSON

{

"meta": {

"timestamp": "string",

"items_page": "string",

"items_page_total": "string",

"items_page_size": "string",

"items_total": "string"

"items": [

{

"attachment": {

"id": "string",

"active": "string",

"created_at": "string",

"modified_at": "string",

"file_id": "string",

"file_download_url": "string",

"record_type": "string",

"record_id": "string",

"mime_type": "string",

"name": "string",

"primary_image": "string",

"notes": "string"

}

"messages": [

]

}

GET

/v1/attachment

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

File

Operations

POST/v1/file GET/v1/file/{id}

Create a File

POST

/v1/file

Creates a single File.

Authorizations

bearerAuth

clientCredentials Flow

Token URL"https://apiv2.ezyvet.com/oauth/token"

Scopes:

Request Body

multipart/form-data

object

Format"binary"

Responses

Successful operation

Content-Type

application/json

JSON

{

"meta": {

"transaction_id": "string",

"timestamp": 0

"items": [

{

"file": {

"id": "string",

"active": true,

"created_at": "string",

"modified_at": "string",

"name": "string",

"size": "string",

"mime_type": "string",

"notes": "string",

"file_download_url": "string"

}

"messages": [

]

}

POST

/v1/file

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

Separation

Operations

GET/v1/separation

Deprecated

Fetch a list of separations

GET

/v1/separation

Its recommended to use the v2/separation endpoint

Authorizations

bearerAuth

clientCredentials Flow

Token URL"https://apiv2.ezyvet.com/oauth/token"

Scopes:

Parameters

Query Parameters

The ID number used by the system to uniquely identify a Separation.

Typestring

active

If true, the Separation is active and usable in ezyVet.

Typestring

created_at

The epoch time when the Separation was created.

Typestring

modified_at

The epoch time when the Separation was last modified.

Typestring

name

The name of the Separation.

Typestring

type

The type of Separation: Database, Business, Division or Location.

Typestring

Enum

"Database""Business""Division""Location"

parent

The ID of the parent Separation. Note, a Database has no parent.

Typestring

contact_id

The ID of the Contact containing business details for this Separation.

Typestring

Responses

A list of separations

Content-Type

application/json

JSON

{

"meta": {

"timestamp": "string",

"items_page": "string",

"items_page_total": "string",

"items_page_size": "string",

"items_total": "string"

"items": [

{

"id": 0,

"created_at": 0,

"modified_at": 0,

"active": true,

"stockadjustment_id": 0,

"product_id": 0,

"name": "string",

"code": "string",

"quantity": 0,

"price": 0,

"ledger_account": 0,

"status": "string",

"batch": [

{

"id": 0,

"created_at": 0,

"modified_at": 0,

"active": true,

"name": "string",

"type": "string",

"parent": 0,

"expiry": 0

}

"location_id": 0

}

"messages": [

"string"

]

}

GET

/v1/separation

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

System Settings

Operations

GET/v1/systemsetting

Get the SystemSettings

GET

/v1/systemsetting

Returns the SystemSetting of the specified site.

Authorizations

bearerAuth

clientCredentials Flow

Token URL"https://apiv2.ezyvet.com/oauth/token"

Scopes:

Responses

Successful response

Content-Type

application/json

JSON

{

"meta": {

"timestamp": "string",

"items_page": "string",

"items_page_total": "string",

"items_page_size": "string",

"items_total": "string"

"items": [

{

"systemsetting": {

"timezone": {

"name": "string",

"utc_offset": "string",

"utc_offset_seconds": 0

}

"messages": [

{

}

]

}

GET

/v1/systemsetting

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

Fetch a list of Tags

GET

/v1/tag

Parameters

Query Parameters

The ID number used by the system to uniquely identify a Tag.

Typestring

active

If true, the Tag is active and usable in ezyVet.

Typestring

created_at

The epoch time when the Tag was created.

Typestring

modified_at

The epoch time when the Tag was last modified.

Typestring

name

The name of the Tag.

Typestring

associated_id

The ID of the record to which this Tag is associated.

Typestring

associated_type

The name of the entity object to which this Tag is associated.

Typestring

category_id

The ID of the TagCategory to which this Tag belongs.

Typestring

Responses

A list of Tags

Content-Type

application/json

JSON

{

"meta": {

"timestamp": "string",

"items_page": "string",

"items_page_total": "string",

"items_page_size": "string",

"items_total": "string"

"items": [

{

"tag": {

"id": "string",

"active": "string",

"created_at": "string",

"modified_at": "string",

"name": "string",

"associated_id": "string",

"associated_type": "string",

"category_id": "string"

}

"messages": [

]

}

GET

/v1/tag

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

Tag Category

Operations

GET/v1/tagcategory

Fetch a list of Tag Categories

GET

/v1/tagcategory

Parameters

Query Parameters

Typestring

active

Typestring

created_at

Typestring

modified_at

Typestring

name

Typestring

Responses

A list of Tag Categories

Content-Type

application/json

JSON

{

"meta": {

"timestamp": "string",

"items_page": "string",

"items_page_total": "string",

"items_page_size": "string",

"items_total": "string"

"items": [

{

"tagcategory": {

"id": "string",

"active": "string",

"created_at": "string",

"modified_at": "string",

"name": "string"

}

"messages": [

]

}

GET

/v1/tagcategory

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

Tag Name

Operations

GET/v1/tagname

Fetches a list containing Tag Names

GET

/v1/tagname

Parameters

Query Parameters

The ID number used by the system to uniquely identify a Tag Name.

Typestring

created_at

The epoch time when the Tag Name was created.

Typestring

modified_at

The epoch time when the Tag Name was last modified.

Typestring

active

If true, the Tag Name is active and usable in ezyVet.

Typestring

category_id

The ID of the Tag Category the Tag Name is part of.

Typestring

Responses

A list of Tag Names

Content-Type

application/json

JSON

{

"meta": {

"timestamp": "string",

"items_page": "string",

"items_page_total": "string",

"items_page_size": "string",

"items_total": "string"

"items": [

{

"tagname": {

"id": "string",

"active": "string",

"created_at": "string",

"modified_at": "string",

"name": "string",

"category_id": "string"

}

"messages": [

]

}

GET

/v1/tagname

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

User

Operations

GET/v1/user

Fetch a list of ezyVet users

GET

/v1/user

Parameters

Query Parameters

The ID number used by the system to uniquely identify a User.

Typestring

active

If true, the User is active and usable in ezyVet.

Typestring

created_at

The epoch time when the User was created.

Typestring

modified_at

The epoch time when the User was last modified.

Typestring

name

The name of the User.

Typestring

code

The code of the User.

Typestring

is_vet

If true, the User is a vet.

Typestring

is_salesperson

If true, the User is a salesperson.

Typestring

limit

Limits the number of items returned.

Typestring

default10

page

Specifies the page number of the result.

Typestring

default1

Responses

A list of Users

Content-Type

application/json

JSON

{

"meta": {

"timestamp": "string",

"items_page": "string",

"items_page_total": "string",

"items_page_size": "string",

"items_total": "string"

"items": [

{

"user": {

"id": "string",

"active": "string",

"created_at": 0,

"modified_at": 0,

"name": "string",

"code": "string",

"is_vet": "string",

"is_salesperson": "string"

}

"messages": [

]

}

GET

/v1/user

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

Webhook Events

Operations

GET/v1/webhookevents

Fetch a list of WebHookEvents

GET

/v1/webhookevents

Authorizations

bearerAuth

clientCredentials Flow

Token URL"https://apiv2.ezyvet.com/oauth/token"

Scopes:

Responses

A JSON object containing the list of WebHookEvents.

Content-Type

application/json

JSON

{

"meta": {

"transaction_id": "string",

"timestamp": 0

"items": [

{

"webhookevents": [

"appointment_created",

"appointment_updated",

"product_created",

"product_updated",

"user_created",

"user_updated",

"consult_created",

"consult_updated",

"therapeutic_created",

"therapeutic_updated",

"therapeutic_disabled",

"default_billing_trigger_created",

"default_billing_trigger_updated",

"default_billing_trigger_disabled",

"bundle_created",

"bundle_updated",

"bundle_disabled"

]

}

"messages": [

]

}

GET

/v1/webhookevents

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

Webhook

Operations

GET/v1/webhooks POST/v1/webhooks DELETE/v1/webhooks/{id}PATCH/v1/webhooks/{id}

Fetch a list of WebHooks

GET

/v1/webhooks

Fetch a WebHook.

Parameters

Query Parameters

The ID number used by the system to uniquely identify a WebHook.

Typenumber

active

If true, the WebHook is active and will cause the webhook_url to receive data upon events being fired.

Typeboolean

event

The name of the subscribed event. Each event is prefixed with a data type (endpoint) followed by the name of the event associated to that data type.

Typestring

Responses

Successful response

Content-Type

application/json

JSON

{

"meta": {

"items_page": 0,

"items_page_total": 0,

"items_page_size": 0,

"items_total": 0,

"transaction_id": "string",

"timestamp": 0

"items": [

{

"webhooks": {

"id": 0,

"created_at": 0,

"modified_at": 0,

"active": true,

"webhook_url": "string",

"event": "string",

"fields": [

"string"

]

}

"messages": [

]

}

GET

/v1/webhooks

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

Separation V2

Operations

GET/v2/separation GET/v2/separation/withprimaryinventorylocation

Fetch a Separation list

GET

/v2/separation

Fetches a list containing Separations.
Separations are a complex part of the ezyVet API and is important to understand.
Please read this document to ensure you have an adequate understanding.

Authorizations

bearerAuth

clientCredentials Flow

Token URL"https://apiv2.ezyvet.com/oauth/token"

Scopes:

Parameters

Query Parameters

The ID number used by the system to uniquely identify a Separation.

Typenumber

uid

The ID number used by the system to uniquely identify a Separation across all ezyVet sites.

Typestring

active

If true, the Separation is active and usable in ezyVet.

Typeboolean

created_at

The epoch time when the Separation was created.

Typenumber

modified_at

The epoch time when the Separation was last modified.

Typenumber

Responses

A list of separations

Content-Type

application/json

JSON

{

"meta": {

"timestamp": "string",

"items_page": "string",

"items_page_total": "string",

"items_page_size": "string",

"items_total": "string"

"items": [

{

"separation": {

"id": 0,

"uid": "ownershipSeparation_d01oHZu5uCuy0VdOgAn23",

"created_at": 0,

"modified_at": 0,

"active": true,

"name": "string",

"type": "string",

"parent": 0,

"child": 0,

"separation_type": "string",

"contact_id": 0,

"contact_uid": "string"

}

"messages": [

{

}

]

}

GET

/v2/separation

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

Site Information

Operations

GET/v3/siteInformation

Get site information

GET

/v3/siteInformation

Gets site information pertaining to the site specified in the request URL.

Responses

Content-Type

application/json

JSON

{

"data": {

"id": "site_jkjBWPng4gFTqRxYkomWU",

"type": "siteInformation",

"attributes": {

"prefix": "apisandbox",

"practiceType": "Mixed Practice",

"version": 40.1

"relationships": {

"timezone": {

"links": {

"related": 94

"data": {

"type": "timezone",

"id": 94

}

"included": [

{

"id": 94,

"type": "timezone",

"attributes": {

"name": "America/Chicago"

}

]

}

GET

/v3/siteInformation

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

ezyVet API ​

What you'll find 🔎 ​

Need more help? 💬 ​

Authenticating ​

When and how often? ​

Errors ​

Field Comparators ​

Examples ​

Paging ​

Page size ​

Large initial syncing ​

Questions ​

Request Throttling ​

API Endpoints​

Authentication​

Operations​

Fetch a JWT bearer token​

Request Body​

Responses​

Samples​

Authentication V2​

Operations​

Fetch a JWT bearer token​

Request Body​

Responses​

Samples​

Contact Management​

Servers​

Address​

Operations​

Fetches a list containing Address(es)​

Authorizations​

Parameters​

Query Parameters

Responses​

Samples​

Communication​

Operations​

Get a Communication​

Authorizations​

Parameters​

ezyVet API

What you'll find 🔎

Need more help? 💬

Authenticating

When and how often?

Errors

Field Comparators

Examples

Paging

Page size

Large initial syncing

Questions

Request Throttling

API Endpoints

Authentication

Operations

Fetch a JWT bearer token

Request Body

Responses

Samples

Authentication V2

Operations

Fetch a JWT bearer token

Request Body

Responses

Samples

Contact Management

Servers

Address

Operations

Fetches a list containing Address(es)

Authorizations

Parameters

Responses

Samples

Communication

Operations

Get a Communication

Authorizations

Parameters