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.

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 token

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

Fetch a JWT bearer token

POST

/v1/oauth/access_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

/v1/oauth/access_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://api.ezyvet.com/v1/oauth/access_token"

Scopes:

Parameters

Query Parameters

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

Type

string

active

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

Type

boolean

created_at

The epoch time when the Attachment was created.

Type

string

modified_at

The epoch time when the Attachment was last modified.

Type

string

record_type

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

Type

string

record_id

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

Type

string

mime_type

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

Type

string

name

The Attachment filename.

Type

string

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

NOTE: It's recommended to use the attachment endpoint

Authorizations

bearerAuth

clientCredentials Flow

Token URL"https://api.ezyvet.com/v1/oauth/access_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://api.ezyvet.com/v1/oauth/access_token"

Scopes:

Parameters

Query Parameters

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

Type

string

active

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

Type

string

created_at

The epoch time when the Separation was created.

Type

string

modified_at

The epoch time when the Separation was last modified.

Type

string

name

The name of the Separation.

Type

string

type

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

Type

string

Valid values

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

parent

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

Type

string

contact_id

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

Type

string

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://api.ezyvet.com/v1/oauth/access_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.

Type

string

active

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

Type

string

created_at

The epoch time when the Tag was created.

Type

string

modified_at

The epoch time when the Tag was last modified.

Type

string

name

The name of the Tag.

Type

string

associated_id

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

Type

string

associated_type

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

Type

string

category_id

The ID of the TagCategory to which this Tag belongs.

Type

string

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

Type

string

active

Type

string

created_at

Type

string

modified_at

Type

string

name

Type

string

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.

Type

string

created_at

The epoch time when the Tag Name was created.

Type

string

modified_at

The epoch time when the Tag Name was last modified.

Type

string

active

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

Type

string

category_id

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

Type

string

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.

Type

string

active

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

Type

string

created_at

The epoch time when the User was created.

Type

string

modified_at

The epoch time when the User was last modified.

Type

string

name

The name of the User.

Type

string

code

The code of the User.

Type

string

is_vet

If true, the User is a vet.

Type

string

is_salesperson

If true, the User is a salesperson.

Type

string

is_dev

If true, the User is an internal ezyVet user. When querying the API, set this field to '0'.

Type

string

limit

Limits the number of items returned.

Type

string

Default

10

page

Specifies the page number of the result.

Type

string

Default

1

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",

"is_dev": "string",

"email": "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://api.ezyvet.com/v1/oauth/access_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.

Type

number

active

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

Type

boolean

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.

Type

string

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://api.ezyvet.com/v1/oauth/access_token"

Scopes:

Parameters

Query Parameters

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

Type

number

uid

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

Type

string

active

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

Type

boolean

created_at

The epoch time when the Separation was created.

Type

number

modified_at

The epoch time when the Separation was last modified.

Type

number

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

User V4

Operations

GET/v4/user POST/v4/user GET/v4/user/{id}PATCH/v4/user/{id}POST/v4/user/bulk PATCH/v4/user/bulk

List all users

GET

/v4/user

Retrieve a paginated list of all users using token-based pagination.

Pagination:

Use the pageSize parameter to control the number of items returned per page (default: 500, max: 500)
Use the nextToken parameter from the response meta object to fetch the next page
The nextToken will be omitted from the meta object when there are no more pages available

Parameters

Query Parameters

pageSize

Maximum number of users to return per page

Type

integer

Minimum

1

Maximum

500

Default

500

nextToken

Token for fetching the next page of results. Obtained from the nextToken field in the response meta object.

Type

string

Example"eyJpZCI6InVzZXJfNjAyYVRJZVY5WHNMME5ZelJjeTFtIn0"

status

Filter users by status (active or disabled)

Type

string

Valid values

"active""disabled"

Responses

Users retrieved successfully

Content-Type

application/json

JSON

{

"meta": {

"nextToken": "XY9mN4pQr2sT8vW1zA3bC"

"data": [

{

"user": {

"id": "user_602aTIeV9XsL0NYzRcy1m",

"name": "John Doe",

"initials": "JD",

"email": "johndoe@email.com",

"login": "joedoe@email.com",

"password": "P@ssw0rd123",

"resetPassword": true,

"mobile": "021 777 8809",

"registration": "9731319",

"qualifications": "Qualified",

"status": "active",

"isVet": true,

"isSalesperson": false,

"roles": [

[

"Veterinarian",

"Practice Manager"

]

}

]

}

GET

/v4/user

Samples

cURLJavaScriptPHPPython

cURL

JavaScript

PHP

Python

ezyVet API ​

What you'll find 🔎 ​

Need more help? 💬 ​

Authenticating ​

When and how often? ​

Errors ​

Paging ​

Page size ​

Request Throttling ​

API Endpoints​

Authentication​

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​

Query Parameters

Responses​

Samples​

Contact​

Operations​

Fetches a list containing Contacts​

Authorizations​

Parameters​

Query Parameters

ezyVet API

What you'll find 🔎

Need more help? 💬

Authenticating

When and how often?

Errors

Paging

Page size

Request Throttling

API Endpoints

Authentication

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

Responses

Samples

Contact

Operations

Fetches a list containing Contacts

Authorizations

Parameters