Getting Started
First Steps
As you are here, you are interested in working with us to provide capability to Veterinary businesses, please contact us (details below) to discuss what you are aiming to acheive.
From a technical viewpoint, you may want access to the sandbox "developer" API environment, please contact us for your client key, secret and tenant-id.
You can use this along with the API explorer (OAS3)
Every key issued will be limited by Scopes for the endpoints they can use, therefore it is important that we provide you access only to what is required in a production environment, however we can open up the sandbox environment fully without limits. The same applies for the 2FA, production environments will be limited to an IP Allow-List, however this restriction does not need to apply for your development.
Contact Us
If you would like to discuss using the VIP then please email us on: integrationplatform@mwiah.co.uk
For any support or incidents with urgent attention:
Telephone: 03300 947 587
Email: support@mwiah.co.uk
Tenants
Tenants or Tenant-Id is a UUID formatted identifier which identifies an individual customer instance of data. Most customers will only have one id, however it is possible a customer has more than 1 Tenant-Id.
You do not need to specify the Tenant-Id when Authenticating, but this must be supplied for each endpoint call.
A Tenant-Id will be supplied to you by MWI Animal Health when authorised by our mutual customer for your business to access their data.
There isn't an endpoint to retrieve all Tenant-Id available to you, you will need to securely store these Id's just like the Client Key and Secret.
Authentication Model
The API requires an access token issued by supplying your Client Key and Secret to the Oauth endpoint. After the JWT access token is issued, you can use this along with supplied Tenant-Id's to call the required endpoints. These endpoints may be limited by Scopes.
This API is a Machine to Machine API for integration between servers and the authentication model only supports this model utilising OAuth2 and JWT formatted access tokens.
Any integration of your interfaces will need to be secured and routed through your own services before communicating with this API to ensure that your Client Key, Secret and Tenant-Id's are not distributed.
Full Details can be found on the Authentication page
You do not need a different client key, secret combo per project, however if your context of use is different such as access to PII (Personally Identifiable Information) for one app but not another, you may request multiple key's for the production environment to limit potential access.
Scopes
Scopes manage which type of endpoint you can use, for example you may be able to Retrieve Contact data, but not Add, Update or Delete Contact data.
Access Tokens
JWT Access tokens are valid for 24 Hours, and you only need one token per Client Key.
The same access token is used across all Tenants.
How the API works
We use request Headers for authentication and authorisation submissions, specifically the Bearer token, and the Tenant-Id.
All endpoint specifics such as search criteria, filters, paging are passed along either by query or on the url path.
Paging is a required component for most data retrieval endpoints, use this to limit the amount of data and request additional pages of data. Paging requirements are only not required when there is a known limited system metadata payload.
Special note for PATCH methods
- Fields indicated as required cannot be set to null
- Any field omitted from the PATCH remains unchanged.
- No field is required in the body, only update fields that need updating.
Domains
Each domain of the API is developed, deployed and managed individually. Every one of these domains will have their own roadmap, lifecycles and releases.
Within the OAS API Explorer you will identify the different domains by the first part of the URL, such as Contact-Management, Patient-Management, Clinical, etc.
You can find the full URL in the example pane (right) by clicking on the Operation and Path (e.g. selecting "GET /accounts" will show the full URL api.vetspace.cloud/account-management/v1/api/accounts)
Pagination and Response Size
Where appropriate the responses from the API are paged, your integration can call subsequent pages after the first results have been returned.
The size of each page can be specified limiting the total number of records returned in a page, therefore if you only need to first 20 records, you can specify this rather than returning 100 or 1000.
Please note that there is a total number of records per page, by default this is 20 records, however certain API endpoints may have different settings which will be detailed in the documentation.
Where paging is available the naming format is consistent as page and size where page is the page number you are asking for, and size is the maximum number of returned records per page.
If these parameters are not supplied, you will automatically be defaulted to page 1 and size 20.
curl --location --request GET 'https://api.vetspace.cloud/contact-management/v1/api/contacts?page=1&size=20
Correlation Id
From release 6 all endpoints will now accept a new header X-Correlation-Id which will allow you to provide your unique request id through to MWI for tracking requests to help troubleshoot any issues you may be experiencing or for correlation of asynchronous requests.
If this is not provided, the MWI VIP API will return an automatically generated UUID in the response. Please provide this in any support requests.