NAV Navbar
cURL

Introduction

By visiting our VetCheck API documentation, you agree to be bound by our Terms of Use and Privacy Policy. Please read these Terms of Use carefully before accessing or using the VetCheck API.

VetCheck is a global content delivery service created for the convenience of vetrinary clinics worldwide.

The VetCheck API is designed to allow streamlined access to VetCheck content via web requests.

Sample requests are given in cURL syntax and should be easily adaptable to any given language.

For support with your application, please contact [email protected]

Roles

VetCheck implements a simple roles-based access system. Some content is availabe to users with a free role code, while most content is only available to users with a premium role code.

Content that is not available to a user's role code will not be returned by the server.

A users role code is determined upon payment for services.

Content Types

When an Accept MIME type other than application/json is requested, the entire response will be of that content type.

# Request an HTML-only response
curl --request GET \
  --url "https://api-v2.vetcheck.it/handouts/{id}" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "accept: text/html"

HTML Paylod is returned

<h1>Handout header</h1>
<p>Body text</p>
<ul>
  <li>List item</li>
</ul>

When requesting a single resource, ie. a handout, VetCheck can return content in a variety of formats for the convenince of consumption by the client application.

Currently supported content types are:

Querying Lists

When requesting a list of content, you are able to filter the returned content using a subset of OData queries.

$count

curl --request GET \
  --url 'https://api-v2.vetcheck.it/handouts?$count' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer ID_TOKEN'

Returns a JSON payload with your query's results count

{ 
  "count": 89
}

The $count filter can be used with any combination of other fitlers to return the number of results in the dataset in place of the data itself.

$orderby

The $orderby directive can be used to specify the order of the results returned, by column and either ASC or DESC.

$top

Returns the first n results returned by the API. Used in combination with $skip to paginate the dataset.

$skip

Will return the results found after the first n results. Used in conjunction with $top to paginate through a dataset.

$filter

Construct filter requests to return specific search results.

curl --request GET \
  --url "https://api-v2.vetcheck.it/handouts?$filter=species eq 'Cat'" \
  --header "accept: application/json" \
  --header "authorization: Bearer ID_TOKEN"

Response contains the resource requested ina JSON array.

{ 
  "handouts" : [
    {}, {}, {}
  ]
}

Complex/nested filters are supported with parens.


  
# Get handouts where keywords contain 'scratching'
curl --request GET \
  --url "https://api-v2.vetcheck.it/handouts?
      $filter=substringof('scratching', keywords)" \
  --header "accept: application/json" \
  --header "authorization: Bearer ID_TOKEN"


The $filter directive is a powerful tool used to filter the content displayed in a dataset. It can be used to effectively construct SQL-style WHERE queries.

The following operators and functions are supported:

Operator/Func Description
Boolean Operators
and and operator
or or operator
Comparison Operators
eq Equals
ne Not Equal
gt Greater Than
gte Greater Than or Equal To
lt Less Than
lte Less Than or Equal To
String Functions
substringof SQL LIKE %% equivelant
endswith String Ends With
startswith String Starts With
tolower Compare to the Lowercase String
toupper Compare to the Uppercase String
trim Remove whitespace

Authentication

VetCheck implements OIDC-compliant OAuth authentication flows. Specifically, the Authorization Code grant type, which allows 3rd party applications to query the VetCheck API on behalf of users.

To use the VetCheck API, register your application by emailing [email protected]. Please supply the following information with your registration request:

Once you are registered, you'll be issued with:

Authorization Code grant type

Stage 1

First stage of the Authorization Code grant flow. Be sure to include the audience, scope(s), response type, client ID, redirect URI, and state.

# Typically this is a redirect frm your application to https://api-v2.vetcheck.it/code
curl --request GET \
  --url 'https://api-v2.vetcheck.it/code' \
    'audience=AUDIENCE' \
    '&scope=SCOPE' \
    '&response_type=RESPONSE_TYPE' \
    '&client_id=YOUR_CLIENT_ID' \
    '&redirect_uri=REDIRECT_URI' \
    '&state=STATE' \
    '&promo_code=PROMO_CODE'

Authorization Code grants involve the following steps:

  1. Direct users to our authentication service, https://api-v2.vetcheck.it/code. This is a simple browser redirect, to be initiated from your application.

  2. Include in your redirect the following required parameters:

  1. The user will be prompted to log in/register if they do not have a current session with VetCheck.
  2. Following log in/registration, the user will be prompted to provide consent to your application.
  3. If/when consent is granted, the user will be redirected back to your application (via. your redirect_uri). Appended to this redirect request is your authorization code.

https://YOUR_REDIRECT_URI?code={code}&state={state}

That is the first stage in the Authorization Code Grant flow. The next stage occurs between your application server and the VetCheck authentication service.

Stage 2

Send the auth code back to VetCheck, along with your client credentials. Your redirect_uri must match exactly the URI supplied in the first stage of the auth flow.

# This is a machine request, and does not involve users/the browser.
curl --request POST \
  --url 'https://api-v2.vetcheck.it/oauth/token' \
  --header 'accept: application/json' \
  --data '{"grant_type":"authorization_code","client_id": "YOUR_CLIENT_ID","client_secret": "YOUR_CLIENT_SECRET",
      "code": "YOUR_AUTHORIZATION_CODE","redirect_uri": "https://YOUR_REDIRECT_URI"}'

Response from stage 2

{
  "ID_TOKEN": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer"
}
  1. Submit the auth code, along with your client ID, client secret, grant type (authorization_code) and the callback URI used previously.
  2. The JSON response contains the ID_TOKEN, refresh_token, id_token, and token_type values.
  3. Congratulations, you are now authorized to access VetCheck! 😎 When querying the VetCheck API, include the id_token in your Authorization header, under bearer scheme authorization.

Access tokens

Example JWT payload

{
  "ID_TOKEN": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "offline_access read:handouts",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}

In order to submit authenticated requests to VetCheck, you'll be using the Bearer authorization scheme, in which you populate the HTTP Authorization header with the value: Authorization: Bearer ID_TOKEN

Access tokens (aka JSON Web Token or JWT) are a compound credential token, consisting of a header, payload, and signature. They cannot be altered or modified in anyway, without invalidating their contents. For this reason, JWTs are essentially opaque to your application. Do not change them or modify them.

Using a JWT inspecter you may see the components of a JWT's payload.

Your application will need to inspect the JWT to determine when it expires. Expired access tokens can no longer be used to authenticate API requests. It's important therefore, to check when your JWT will expire (or has expired) so that you may refresh it...

Refresh tokens

To request a new access token using your refresh token, call our /oauth/token endpoint

curl --request POST \
  --url 'https://api-v2.vetcheck.it/oauth/token' \
  --header 'accept: application/json' \
  --data '{ "grant_type": "refresh_token", "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET", "refresh_token": "USERS_REFRESH_TOKEN" }'

The response contains a new token, and the number of seconds to the new token's expiry.

{ 
  "ID_TOKEN": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "offline_access ...",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}

Credentials supplied through the auth code grant include an id_token, which is used to authenticate API queries, and optionally a refresh_token. To request a refresh token, include the scope offline_access in your initial auth request/redirect to GET /oauth/token.

As JWT access tokens have a built-in expiry, refresh tokens are used to refresh an access token. Refresh tokens are therefore very secret, and while they can be retained within your application, they should be treated as if they were a username and password.

Audience

Your audience parameter in auth requests will always be the VetCheck API:

https://api-v2.vetcheck.it/

Include the trailing forward slash.

Species

List Categories

curl --request GET \
  --url "https://api-v2.vetcheck.it/species" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "accept: application/json"

Filters can be applied via the $filter parameter.

curl --request GET \
  --url "https://api-v2.vetcheck.it/species?
        $filter=name eq 'Horse'" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "accept: application/json"

This endpoint retrieves a list of species that can be used while filtering lists.

HTTP Request

GET https://api-v2.vetcheck.it/species?{$filter}{$orderby}{$top}{$skip}{$count}

Filter Parameters

Search Parameter Description
name Species Name

Handouts

List Handouts

curl --request GET \
  --url "https://api-v2.vetcheck.it/handouts" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "accept: application/json"

Adding search parameters to your $filter will add properties to the handout list response. Note the addition of the species and species_id attributes in the response to this query.

curl --request GET \
  --url "https://api-v2.vetcheck.it/handouts?
        $filter=species eq 'Horse'" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "accept: application/json"

This endpoint retrieves a list of handouts.

HTTP Request

GET https://api-v2.vetcheck.it/handouts?{$filter}{$orderby}{$top}{$skip}{$count}

Filter Parameters

The VetCheck API search index collates handouts against a variety of attributes, many of which can be retrieved through the API.

By manipulating the $filter query string, one can customise the returned list of handouts. For example, retireve a list of 'Cat' handouts with the keyword 'Fleas' to retrieve articles about Cat Fleas.

The returned result set will not contain extra fields for metadata, as it is assumed one is running a filtered query against the API in order to customise output--not using the output in order to construct ones own lookup table.

In order to retrieve a handout's content, it is best practice to make a request for each unique handout that the user requests, i.e. GET https://api-v2.vetcheck.it/handouts/{id}.

The following filters are available in the API:

Search Parameter Description
title Handout title
keywords Comma separated keywords
created_at Document creation date (UTC)
updated_at Document creation date (UTC)
updated_by User (Auth0) ID of a user in your account (custom content only)
country_code Two-character country code (linked to location)
species Text based species
species_id ID based species (from /species)

Retrieve a Handout

curl --request GET \
  --url "https://api-v2.vetcheck.it/handouts/2" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "accept: application/json"

This endpoint will retrieve a specified handout from the VetCheck servers, on the condition that the handout is within your user's access level restriction, and (if it is custom content) the User ID matches the one uised to retrieve the handout.

HTTP Request

GET https://api-v2.vetcheck.it/handouts/{id}

URL Parameters

Parameter Description
id The Unique ID of the handout to retrieve

Update a Handout

curl --request PUT \
  --url "https://api-v2.vetcheck.it/handouts/2" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "content-type: application/json"
  --data '{ "title": "My new title" }'

This endpoint will create a custom handout, usually updating a specific handout with custom contnet. You may only update handouts that belong to the account of the authenticated user, or are standard VetCheck content.

Modifying default content will duplicate the article into your account and create a new unique ID to access your version of the content.

Modifying custom content will update the custom content.

HTTP Request

PUT https://api-v2.vetcheck.it/handouts/{id}

URL Parameters

Parameter Description
id The Unique ID of the handout to update

Body Parameters

Parameter Description
title The title of the handout
keywords Keywords used to search for this content
html Raw HTML of the handout (Markdown, Raw and Plain Text version will be auto-generated)
Parameters for search table (optional unless otherwise specified)
species_id Associated Species ID
breed_id Associated Breed ID
location_id Associated Location ID

Share a Handout

curl --request POST \
  --url "https://api-v2.vetcheck.it/handouts/2/share" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "content-type: application/json" \
  --data '{ "name": "Bluey", "email": "[email protected]", "comments": "See you at your next appointment Bluey!" }'

This endpoint creates a handout share. A shared handout will produce a share URL (sharelink), which you may supply to another party, in order to share a handout with them. You may optionally include comments, special instructions and next appointment date and time. This is suitable for cases where you are sharing a handout after a consultation.

HTTP Request

POST https://api-v2.vetcheck.it/handouts/{id}/share

URL Parameters

Parameter Description
id The Unique ID of the handout to share

Body Parameters

Parameter Description
name The name of the pet
email Email with whom the handout should be linked
comments Additional comments
special_instructions Special instructions
next_appointment Next appointment timestamp (UTC)

Limits

All users are limited to 5 shares per minute. This applies across all shareable resources. Requesting more than 5 shares in a minute will produce an HTTP 429 response.

Forms

List forms

curl --request GET \
  --url "https://api-v2.vetcheck.it/forms" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "accept: application/json"

Adding search parameters to your $filter will add properties to the form list response.

curl --request GET \
  --url "https://api-v2.vetcheck.it/forms?
        $filter=country_code eq 'AU'" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "accept: application/json"

This endpoint retrieves a list of forms.

HTTP Request

GET https://api-v2.vetcheck.it/forms?{$filter}{$orderby}{$top}{$skip}{$count}

Filter Parameters

The VetCheck API search index collates forms against a variety of attributes, many of which can be retrieved through the API.

By manipulating the $filter query string, one can customise the returned list of forms. For example, retrieve a list of 'Cat' forms with the keyword 'Fleas' to retrieve articles about Cat Fleas.

The returned result set will not contain extra fields for metadata, as it is assumed one is running a filtered query against the API in order to customise output--not using the output in order to construct ones own lookup table.

In order to retrieve a form's content, it is best practice to make a request for each unique form that the user requests, i.e. GET https://api-v2.vetcheck.it/forms/{id}.

The following filters are available in the API:

Search Parameter Description
title Form title
keywords Comma separated keywords
created_at Document creation date (UTC)
updated_at Document creation date (UTC)
updated_by User (Auth0) ID of a user in your account (custom content only)
country_code Two-character country code (linked to location)

Update a Form

curl --request PUT \
              --url "https://api-v2.vetcheck.it/forms/2" \
              --header "authorization: Bearer ID_TOKEN" \
              --header "content-type: application/json"
            

This endpoint will create a custom form, usually updating a specific form with custom content. You may only update forms that belong to the account of the authenticated user, or are standard VetCheck content.

Modifying default content will duplicate the form into your account and create a new unique ID to access your version of the content.

Modifying custom content will update the custom content.

HTTP Request

PUT https://api-v2.vetcheck.it/forms/{id}

URL Parameters

Parameter Description
id The Unique ID of the form to update

Body Parameters

Parameter Description
title The title of the form
keywords Keywords used to search for this content

Retrieve a Form

curl --request GET \
  --url "https://api-v2.vetcheck.it/forms/2/get" \
  --header "authorization: Bearer ID_TOKEN" \
  --header "accept: application/json"

This endpoint will retrieve a specified form from the VetCheck servers, on the condition that the form is within your user's access level restriction, and (if it is custom content) the User ID matches the one uised to retrieve the form.

HTTP Request

GET https://api-v2.vetcheck.it/forms/{id}/get

URL Parameters

Parameter Description
id The Unique ID of the form to retrieve

Prefill a Form

 

This endpoint creates a form share. A shared form will produce a share URL (sharelink), which you may supply to another party, in order to share a form with them. You may optionally include comments, special instructions and next appointment date and time. This is suitable for cases where you are sharing a form after a consultation.

HTTP Request

POST https://api-v2.vetcheck.it/forms/{id}/share

URL Parameters

Parameter Description
id The Unique ID of the form to share

Body Parameters

Based on a successful API form request, you also have the ability to pre-fill a form based on the following parameters:



Form location Pre-fill variable name
All forms (global header) firstName
All forms (global header) lastName
All forms (global header) ownerEmail
All forms (global header) ownerPhone
All forms (global header) petName
All forms (global header) petSpecies
All forms (global header) petBreed
All forms (global header) petSex
All forms (global header) petDateOfBirth
Desexing certificate form_client_address
Desexing certificate form_pet_desexing_date
Health certificate form_pet_microchip
Vaccination certificate form_pet_last_vaccine
Vaccination certificate form_pet_last_vaccine_date
Vaccination certificate form_pet_next_vaccine_date


Example prefill html code

document.getElementById("firstName").value = "{your_client_first_name}";

Share a Form

   
            curl --request POST \
          --url "https://api-v2.vetcheck.it/forms/2/share" \
          --header "authorization: Bearer ID_TOKEN" \
          --header "content-type: application/json" \
          --data '{ "name": "Bluey", "email": "[email protected]", "comments": "See you at your next appointment Bluey!" }'
          

This endpoint creates a form share. A shared form will produce a share URL (sharelink), which you may supply to another party, in order to share a form with them. You may optionally include comments, special instructions and next appointment date and time. This is suitable for cases where you are sharing a form after a consultation.

HTTP Request

POST https://api-v2.vetcheck.it/forms/{id}/share

URL Parameters

Parameter Description
id The Unique ID of the form to share

Body Parameters

Parameter Description
name The name of the pet
email Email with whom the form should be linked
comments Additional comments
special_instructions Special instructions
next_appointment Next appointment timestamp (UTC)

At the bottom of the share window, you can click "Generate Link". This unique link will create a new form to complete and the results will be submitted to the clinic who generated the link. This can be used for marketing e.g. social media, newsletter, website. Please note that by generating a share link this will not be emailed until submitted.

Submit a Form

To submit a form a user will need to click on the unique share URL (sharelink) sent via email from the share feature. This will display the form in the browser to display the incomplete form. Once the form is submitted a new email is sent to the user and the clinic. The same share link will display the results submitted via the form.

Vet Forms

List vet forms

        curl --request GET \
          --url "https://api-v2.vetcheck.it/vetforms" \
          --header "authorization: Bearer ID_TOKEN" \
          --header "accept: application/json"
        
      

This endpoint retrieves a list of vet forms.

HTTP Request

GET https://api-v2.vetcheck.it/vetforms?{$filter}{$orderby}{$top}{$skip}{$count}

Filter Parameters

The VetCheck API search index collates forms against a variety of attributes, many of which can be retrieved through the API.

By manipulating the $filter query string, one can customise the returned list of forms. For example, retrieve a list of 'Cat' forms with the keyword 'Fleas' to retrieve articles about Cat Fleas.

The returned result set will not contain extra fields for metadata, as it is assumed one is running a filtered query against the API in order to customise output--not using the output in order to construct ones own lookup table.

In order to retrieve a form's content, it is best practice to make a request for each unique form that the user requests, i.e. GET https://api-v2.vetcheck.it/vetforms/{id}.

The following filters are available in the API:

Search Parameter Description
title Form title
keywords Comma separated keywords
created_at Document creation date (UTC)
updated_at Document creation date (UTC)
updated_by User (Auth0) ID of a user in your account (custom content only)
status This will return status of form i.e. incomplete, reminded, complete

Retrieve a Vet Form

  curl --request GET \
    --url "https://api-v2.vetcheck.it/vetforms/2/get" \
    --header "authorization: Bearer ID_TOKEN" \
    --header "accept: application/json"
  
  

This endpoint will retrieve a specified form from the VetCheck servers, on the condition that the form is within your user's access level restriction, and (if it is custom content) the User ID matches the one uised to retrieve the form.

HTTP Request

GET https://api-v2.vetcheck.it/vetforms/{id}/get

URL Parameters

Parameter Description
id The Unique ID of the form to retrieve

Submit a Vet Form

When a Vet form is completed, a copy of is automatically emailed to the clinic. Select vet forms also have the option to also share directly with the pet owner e.g. Desexing certificate, Ultrasound report, Dental chart

Programs

List Programs

curl --request GET \
      --url "https://api-v2.vetcheck.it/programs" \
      --header "authorization: Bearer ID_TOKEN" \
      --header "accept: application/json"
    

Adding search parameters to your $filter will add properties to the program list response. Note the addition of the species and species_id attributes in the response to this query.

curl --request GET \
      --url "https://api-v2.vetcheck.it/programs?
            $filter=species eq 'Horse'" \
      --header "authorization: Bearer ID_TOKEN" \
      --header "accept: application/json"
    

This endpoint retrieves a list of programs.

HTTP Request

GET https://api-v2.vetcheck.it/programs?{$filter}{$orderby}{$top}{$skip}{$count}

Filter Parameters

The VetCheck API search index collates programs against a variety of attributes, many of which can be retrieved through the API.

By manipulating the $filter query string, one can customise the returned list of programs. For example, retireve a list of 'Cat' programs with the keyword 'Fleas' to retrieve articles about Cat Fleas.

The returned result set will not contain extra fields for metadata, as it is assumed one is running a filtered query against the API in order to customise output--not using the output in order to construct ones own lookup table.

In order to retrieve a program's content, it is best practice to make a request for each unique program that the user requests, i.e. GET https://api-v2.vetcheck.it/programs/{id}.

The following filters are available in the API:

Search Parameter Description
title Program title
keywords Comma separated keywords
created_at Document creation date (UTC)
updated_at Document creation date (UTC)
updated_by User (Auth0) ID of a user in your account (custom content only)
species Text based species
species_id ID based species (from /species)

Retrieve a program

curl --request GET \
      --url "https://api-v2.vetcheck.it/programs/2" \
      --header "authorization: Bearer ID_TOKEN" \
      --header "accept: application/json"
    

This endpoint will retrieve a specified program from the VetCheck servers, on the condition that the program is within your user's access level restriction, and (if it is custom content) the User ID matches the one uised to retrieve the program.

HTTP Request

GET https://api-v2.vetcheck.it/programs/{id}

URL Parameters

Parameter Description
id The Unique ID of the program to retrieve

Update a program

curl --request PUT \
      --url "https://api-v2.vetcheck.it/programs/2" \
      --header "authorization: Bearer ID_TOKEN" \
      --header "content-type: application/json"
      --data '{ "title": "My new title" }'
    

This endpoint will create a custom program, usually updating a specific program with custom contnet. You may only update programs that belong to the account of the authenticated user, or are standard VetCheck content.

Modifying default content will duplicate the article into your account and create a new unique ID to access your version of the content.

Modifying custom content will update the custom content.

HTTP Request

PUT https://api-v2.vetcheck.it/programs/{id}

URL Parameters

Parameter Description
id The Unique ID of the program to update

Body Parameters

Parameter Description
title The title of the program
keywords Keywords used to search for this content
html Raw HTML of the program (Markdown, Raw and Plain Text version will be auto-generated)
Parameters for search table (optional unless otherwise specified)
keywords Keywords used to search for this content
breed_id Associated Breed ID
location_id Associated Location ID

Share a program

curl --request POST \
      --url "https://api-v2.vetcheck.it/programs/2/share" \
      --header "authorization: Bearer ID_TOKEN" \
      --header "content-type: application/json" \
      --data '{ "name": "Bluey", "email": "[email protected]", "comments": "Here is the program for Bluey!" }'
    
    

This endpoint creates a program share. A shared program will produce a share URL (sharelink), which you may supply to another party, in order to share a program with them. You may optionally include comments, special instructions and next appointment date and time. This is suitable for cases where you are sharing a program after a consultation.

HTTP Request

POST https://api-v2.vetcheck.it/programs/{id}/share

URL Parameters

Parameter Description
id The Unique ID of the program to share

Body Parameters

Parameter Description
name The name of the pet
email Email with whom the handout should be linked
comments Additional comments
special_instructions Special instructions
next_appointment Next appointment timestamp (UTC)

Limits

All users are limited to 5 shares per minute. This applies across all shareable resources. Requesting more than 5 shares in a minute will produce an HTTP 429 response.

Errors

If a request is invalid, or produces an invalid resposne, an error message will be thrown.

A list of error messages reported by the API is below

Error Code Error Message Meaning
400 Bad Request Your request is invalid.
401 Unauthorized Your id_token is not valid.
403 Forbidden You are not authorised to access the content.
404 Not Found The content could not be found.
405 Method Not Allowed You tried to use the worng request method on a resource.
406 Not Acceptable You submitted an invalid response type.
429 Too Many Requests You have been rate limited.
500 Internal Server Error The API could not process your request and threw an unsp[ecified error
503 Service Unavailable The API is down for maintenance