Accessing the API

This guide is for external integrations that need to work on behalf of users. The API is available through the connect.vetcove.com domain. You will need a Vetcove provision OAuth Application in our system to begin connecting Clinics and making requests. Please reach out to your support contact for help getting started.

Authentication

Authentication to the Vetcove service is done via OAuth 2.0 to grant access to resources on behalf of our users.

Important Values

Once an account has been provisioned, head to your Integrator Portal page to view your Client Id and list of connected clinics. These are going to be the gateway to interacting with Vetcove.

Available OAuth 2.0 scopes

You will need to specify what type of access the user is granting to your application when going through the OAuth 2.0 consent flow. The available scopes are:

Scope name	Description
all	Grants a token access to all scopes
auto_auth	Allows creation of links which will automatically login a client
addresses:read	Read address records
addresses:write	Modify address records
clinics:read	Read clinic records
clinic_clients:read	Read clinic client records
clinic_clients:write	Modify clinic client records
clinic_patients:read	Read clinic patient records
clinic_patients:write	Modify clinic patient records
appointments:read	Read appointment records
appointments:write	Modify appointment records
calendars:read	Read calendar records
client_onboardings:read	Read client onboarding records
care_plans:read	Read care plan records
care_plans:write	Modify care plan records
patient_standard_care_reminders:read	Read patient standard care reminder records
invoices:read	Read invoice records
labs:read	Read lab records
prescriptions:read	Read prescription records
external_rx:read	Read external prescription records
payment_methods:read	Read payment method records
payment_methods:write	Modify payment method records
payment_transactions:read	Read payment transaction records
payment_links:read	Read payment link records
payment_links:write	Modify payment link records
service_pricing:read	Read service pricing configurations
service_pricing:write	Modify service pricing configurations
catalog:read	Read catalog records
subscriptions:read	Read subscription records
orders:read	Read order records
checkout_links:read	Read checkout link records
pdfs:read	Read PDF records
pdfs:write	Modify PDF records
uploaded_files:read	Read which files have been previously uploaded
uploaded_files:write	Upload new files into the system
inventory:read	Read which inventory codes exist and their associated settings
inventory:write	Modify settings for inventory codes
medical_records:read	Read medical record, vital, and assessment records
patient_client_relationships:read	Read patient client relationship records
patient_client_relationships:write	Modify patient client relationship records

Note that while you may request any of the above scopes, not all features will be accessible to all users through the API.

Clinic Authorization

From your software, add in a “Connect with Vetcove” button that when clicked, will redirect the user (with a GET request) to the following url:

connect.vetcove.com/api/clinic/v1/app_store/oauth/authorize/?response_type=code&client_id=<client_id>&scope=<scope>&state=<uri_encoded_state_string>&redirect_uri=<uri>&code_challenge=<code_challenge>&code_challenge_method=S256

Notes:

The client_id in the URL is taken from the tokens page
The scope is a whitespace-delimited sequence of scopes you are requesting access to
The state value is a url encoded string that will be passed through to the redirect URI
The redirect_uri value is a fully-qualified url that has been whitelisted in the Integrator Portal
The code_challenge is a PKCE code challenge derived from a randomly generated code_verifier. Generate a random string (the code_verifier), then compute BASE64URL(SHA256(code_verifier)) to produce the code_challenge.
The code_challenge_method must be S256

Clinic Account Specificiation: Redirecting to /api/clinic/v1/app_store/oauth/authorize/ will prompt the user to enter valid Vetcove Clinic Credentials. These are credentials that work on https://pims.vetcove.com.

Successful Authorization

When a clinic successfully completes the Oauth grant, the redirect-uri specified will be called with the query parameters <redirect-uri>?code=<auth_code>&state=<uri_encoded_state_string> Notes:

The code will expire after 10 minutes and should be used immediately for requesting an access_token

Requesting Access Tokens

Once a code has been successfully delivered to your redirect uri, the code, client_id, and client_secret will be used for requesting access_tokens This is done with a POST request to connect.vetcove.com/api/external/v1/app_store/oauth/token/ with the payload

{
    'code': <code>,
    'client_id': <client_id>,
    'client_secret': <client_secret>,
    'grant_type': 'authorization_code',
    'code_verifier': <code_verifier>
}

Notes:

The code is a one-time code
The grant_type of authorization_code is required
The code_verifier is the original random string used to generate the code_challenge in the authorization request

If your application is configured with multiple redirect_uris, then redirect_uri is required as a part of the payload. This value needs to match what was in the /api/clinic/v1/app_store/oauth/authorize/ call. Otherwise, a 400 response code and Mismatching redirect URI. error will be returned.

{
    ... payload ...,
    'redirect_uri': '<redirect-uri>'
}

A response will be in the form:

{
    'access_token': <access_token>,
    'expires_in': 3600,
    'token_type': 'Bearer',
    'scope': 'clinic_clients:read clinic_patients:read',
    'refresh_token': <refresh_token>
}

Notes:

The access_token has an expiry of 60 minutes
The access_token can be stored in temporary storage for subsequent requests
The refresh_token should be stored in long term storage for subsequent requests
Access Tokens must be submitted via Authorization: Bearer <access_token> header

Requesting a Refresh Token

We strongly recommend that you build your application to expect token expiry at any time. You can do this by adding an error handler for all requests in case they get an “expired token” error message. To request a new token, make another POST request to connect.vetcove.com/api/external/v1/app_store/oauth/token/ with the payload

{
    'grant_type': 'refresh_token',
    'refresh_token': <refresh_token>,
    'client_id': <client_id>,
    'client_secret': <client_secret>,
}

Notes:

The refresh_token is the the token saved from the previous token grant
The refresh_token can be used only once, and subsequent requests require a new refresh_token. Note: There is a 5 minute grace period between when a refresh_token is used, and when it expires. This is useful when facing network issues during this API call. This means retries using the same refresh_token are allowed within this grace period.

A response will be in the same form as above:

{
    'access_token': <access_token>,
    'expires_in': 3600,
    'token_type': 'Bearer',
    'refresh_token': <refresh_token>
}

Using the API

Developer guides

Accounts

Care plans

Catalog

Checkout links

Clients & patients

Clinics

External Rx

Insurance

Inbox

Invoices

Labs

Onboardings

Orders

Payments

PDFs

Prescriptions

Scheduler

Service pricing

Standard care

Subscriptions

File uploads

Inventory

Forms

Medical records

Getting started with OAuth

Accessing the API

Authentication

Important Values

Available OAuth 2.0 scopes

Clinic Authorization

Successful Authorization

Requesting Access Tokens

Requesting a Refresh Token

​Accessing the API

​Authentication

​Important Values

​Available OAuth 2.0 scopes

​Clinic Authorization

​Successful Authorization

​Requesting Access Tokens

​Requesting a Refresh Token

Accessing the API

Authentication

Important Values

Available OAuth 2.0 scopes

Clinic Authorization

Successful Authorization

Requesting Access Tokens

Requesting a Refresh Token