Migrate from v2

This page has been put together for our integration partners and customers who are currently using the v2 API, here we will guide you through the high-level plan, confirmed details and common questions.

If you are not currently using the v2 API Gateway, then you do not need to continue on this page.

What is the v2 API Gateway?

When we discuss the v2 API, we are actually referring to a previous generation of API's served through a different gateway.

This documentation site is for our third-generation (v3) API gateway and has been planned from the beginning to be the final gateway with an evolving and expanding holistic view of the practices data.

How is v3 different from v2?

The new gateway and endpoints are very different from their v2 counterparts both in scope and purpose.

v2 has very specific use-cases for the endpoints which in many cases orchestrated the flows on your behalf, however with v3 we are not creating artificial limits and restrictions on what you could do, but you will need to orchestrate your required flows.

For example: Now adding new data may include multiple POST requests where previously this was a single request. e.g. Email, Numbers, addresses are all separate endpoints from a contact record. However this means you have greater control because of the granularity and could for example progressively build a clients profile.

v3 will also have more endpoint options as standard to optimise your data usage such as paging, sorting and filtering.

Can we reuse v2 endpoints in v3?

Unfortunately not, you should plan for redevelopment of your integration against the new endpoints.

This is due to the way we are now fully opening up all data entities, therefore a different approach to these resources (e.g. contact, email, numbers) and operations (POST, GET, etc) are required.

What are the main differences?

When you start using our API explorer and documentation, you will notice the following:

• UUID - We now use UUID (Universally Unique IDentifiers) for identifiers instead of integer. Therefore your system will need to be able to store string or natively uuid/guid.
• Authentication - We now use JWT access tokens which refresh once a day not every 15 minutes. Client Key and Secret is only provided to us once per day.
• Tenant-Id - We use a UUID for identifying the customer tenant rather than the previous GroupId.
• Endpoints have a singular purpose instead of multiple.
• Domains - Endpoints are divided into groupings that will reference resources in other domains. These domains all have their own release cycles.

Can we use v2 and v3 at the same time?

Short Answer: Yes for now.

Yes, you can use both v2 and v3 API gateways at the same time and each Merlin PMS can handle requests from both at the same time. However note differences between the 2 gateways above.

As the identifiers are different between the 2 gateways, there are some key identifiers we have created endpoints for your conversion.

• Patient Ids
• Contact and Account Ids (in the Contact OAS)
• Appointment Ids
• Formulary Ids (Code Id)
• Location Ids (Site Id)

note

v2 ends support and operation July 2024, therefore you should plan a development cycle to complete the transition completely to v3.

When will v3 be available?

Short Answer: It is available now, and more development is planned as required.

Endpoints have been available since November 2021 and have been continually added to since, in the tables below you can find the mapping plus any area's we do not plan to include in the new gateways.

We are continuously reviewing and prioritising our API roadmap, the endpoints of v3 are being developed and released in a continuous fashion; as endpoints are designed, developed and tested, they will be released.

When is v2 capability available in v3?

This has now been completed and released, any existing gaps are either not planned for work or discussion with their primary users.

When will v2 no longer be available to use?

Consumers of the v2 API will be notified and have around 12 months before the planned shutdown date, we will provide as much assistance as we can to help you acheive the goal of migrating.

Migration Mapping

Accounts, Banking & Client Link Services

v2 API	v3 Equivilent
GET Accounts/Account Items	GET billing/invoices GET billing/invoices/uuid/invoice-contents
GET Accounts/Client Balance	GET billing/uuid/balance
POST Accounts/Donations POST Accounts/Payments	POST billing/payments
GET Banking/Banking Details	NEW GET billing/payments/summary
Client Link	No replacement planned for this space.
GET Client Link/Avg Wait For All Sites GET Client Link/Avg Wait For Site	GET Waiting Times

Clients Service

v2 API	v3 Equivilent
GET Clients/Account Categories	GET Account-Management/account-categories
POST Clients/Add Patient	POST Patient-Management/patients
GET Clients/Address Types	GET Contact-Management/address-types
GET Clients/Breeds	GET Patient-Management/breeds
POST Clients/Client Appointments	GET Calendar-Management/appointments
GET Clients/Client Categories	GET Account-Management/account-types
GET Clients/Client Communications	GET Communication logs POST Communication logs
GET Clients/Client Documents	GET Document metadata
POST Clients/Client Notes	GET Contact Notes GET Contact Note POST Contact Note PATCH Contact Note DELETE Contact Note GET Contacts Notes
POST Clients/Clients	GET Contact-Management/contacts GET Contact-Management/contacts/uuid/communication-preferences GET Contact-Management/titles GET Contact-Management/contacts/uuid/addresses GET Contact-Management/contacts/uuid/emails GET Contact-Management/contacts/uuid/numbers GET Account-Management/introduced-by-types GET Account-Management/accounts/uuid/contacts GET Account-Management/accounts
PUT Clients/Clients	PATCH Contact PATCH Contact Addresses PATCH Contact Emails PATCH Contact Numbers DELETE Contact Addresses DELETE Contact Emails DELETE Contact Numbers
GET Clients/Colours/Breed	GET Patient-Management/breeds/uuid/colours GET Patient-Management/colours/uuid
GET Clients/Consent History	GET Contact-Management/contacts/uuid/data-consent
GET Clients/Email Types	GET Contact-Management/email-address-types
GET Clients/Genders by Species	GET Patient-Management/species/uuid/genders GET Patient-Management/genders/uuid
GET Clients/Genders All	GET Patient-Management/genders
GET Clients/Insurance Companies	GET Insurance Companies
GET Clients/Introduced By	GET Account-Management/introduced-by-types
GET Clients/Mobile Types	GET Contact-Management/number-types
GET Clients/Patient Categories	GET Patient-Management/patient-categories
POST Clients/Patients	DELETE Deactivate Patient PATCH Activate Patient
GET Clients/Sites	GET Location-Management/locations
GET Clients/Species by Patient Category	GET Patient-Management/patient-categories/uuid/species GET Patient-Management/species/uuid
GET Clients/Towns	GET Contact-Management/cities
PATCH Clients/Update Patient	PATCH Patient
POST Clients/Weights	GET Clinical/vital-metrics/weight DELETE Weight

Clinical Portal Service

v2 API	v3 Equivilent
POST Clinical Portal/Create Clinical Note	Posting Clinical notes in v3 requires usages of additional metadata. v2 only allowed a single note entry, however it is now possible to record the entire clinical protocol. GET Clinical Categories GET Clinical Answers GET Clinical Code Categories GET Clinical Codes GET Protocols GET Protocol Questions GET Question Answers POST Clinical Notes
GET Clinical Portal/Get Appointments	GET Calendar-Management/appointments
GET Clinical Portal/Get Client	GET Contact-Management/contacts GET Contact-Management/contacts/uuid/communication-preferences GET Contact-Management/titles GET Contact-Management/contacts/uuid/addresses GET Contact-Management/contacts/uuid/emails GET Contact-Management/contacts/uuid/numbers GET Account-Management/introduced-by-types GET Account-Management/accounts/uuid/contacts GET Account-Management/accounts
GET Clinical Portal/Get Patient	GET Patient-Management/patients
GET Clinical Portal/Patient Reminders GET Clinical Portal/Get Reminders	GET Reminders/patient-reminders
GET Clinical Portal/Get Sites	GET Location-Management/locations

Code Entry Service

v2 API	v3 Equivilent
GET Code Entry/Deviations	GET Formulary-Management/location-deviations
PUT Code Entry/Deviations	NEW PATCH Formulary-Management/location-deviations
GET Code Entry/Discounts	Discount Codes are included in the Services endpoint.
PATCH Code Entry/Discounts	Discount Codes are included in the Services endpoint.
POST Code Entry/Discounts	Discount Codes are included in the Services endpoint.
PUT Code Entry/Price Updates	COMING SOON Reference: API-533
GET Code Entry/Services	GET Formulary-Management/services
PATCH Code Entry/Services	PATCH Service Configuration
POST Code Entry/Services	POST Service Configuration
GET Code Entry/Stock Codes	GET Formulary-Management/stock
PATCH Code Entry/Stock Codes	PATCH Stock Configuration
POST Code Entry/Stock Codes	POST Stock Configuration
New API's for managing metadata are being included in v3, we will no longer have embedded arrays within Stock, Service and Discount endpoints.	Dispensing notes: PATCH Dispensing Notes POST Dispensing Notes DELETE Dispensing Notes GET Dispensing Notes Formulary groups: GET Formulary Groups Send to actions: GET Send-To Actions PATCH Send-To Actions POST Send-To Actions DELETE Send-To Action Discount categories: GET Discount Categories PATCH Discount Category POST Discount Category DELETE Discount Category Notes: GET Formulary Notes POST Formulary Note PATCH Formulary Note DELETE Formulary Note

Eligibility, Mobile & Prospect Bookings Services

v2 API	v3 Equivilent
Eligibility Service	GET contact-management/contacts/:contact-uuid/eligibility-registration NEW GET contact-management/eligibility/presented-documents NEW GET contact-management/eligibility/presented-identification NEW GET contact-management/eligibility/activiation-reasons NEW POST contact-management/contacts/:contact-uuid/eligibility-registration NEW POST patient-management/patients/eligibility-deactivate NEW POST patient-management/patients/:patient-uuid/eligibility-deactivate NEW POST patient-management/patients/:patient-uuid/eligibility-activation
Mobile Service	To Do This is on our backlog.
POST Prospect Bookings/Book Appointment	POST Calendar-Management/appointments
GET Prospect Bookings/Check Appointment	GET Calendar-Management/appointments/uuid
POST Prospect Bookings/Delete Appointment	DELETE Calendar-Management/appointments/uuid
GET Prospect Bookings/Get Appointment Reasons	GET Calendar-Management/reasons
GET Prospect Bookings/Get Available Slots	GET Calendar-Management/availability/location-uuid/available
GET Prospect Bookings/Get Client	GET Contact-Management/contacts GET Contact-Management/contacts/uuid/communication-preferences GET Contact-Management/titles GET Contact-Management/contacts/uuid/addresses GET Contact-Management/contacts/uuid/emails GET Contact-Management/contacts/uuid/numbers GET Account-Management/introduced-by-types GET Account-Management/accounts/uuid/contacts GET Account-Management/accounts
GET Prospect Bookings/Get Notes	GET Availability Blocks
GET Prospect Bookings/Get Patients	GET Patient-Management/patients
GET Prospect Bookings/Get Sites	GET Location-Management/locations
GET Prospect Bookings/Get Surgeons	GET Contact-Management/practitioners

Registrations Service

v2 API	v3 Equivilent
GET Registrations/Breeds	GET Patient-Management/breeds
GET Registrations/Categories	GET Patient-Management/patient-categories
POST Registrations/Clients	POST Contact-Management/contacts POST Contact-Management/contacts/uuid/communication-preferences POST Contact-Management/contacts/uuid/addresses POST Contact-Management/contacts/uuid/data-consent POST Contact-Management/contacts/uuid/emails POST Contact-Management/contacts/uuid/numbers
GET Registrations/Colours	GET Patient-Management/breeds/uuid/colours GET Patient-Management/colours/uuid
GET Registrations/Genders	GET Patient-Management/species/uuid/genders GET Patient-Management/genders/uuid
GET Registrations/Introduced By	GET Account-Management/introduced-by-types
GET Registrations/is Client Registered	GET Contact-Management/contacts/numbers GET Contact-Management/contacts/emails
GET Registrations/List Cities	GET Contact-Management/cities
GET Registrations/PMS Sites by Group	GET Location-Management/locations
GET Registrations/Species	GET Patient-Management/species/uuid/genders GET Patient-Management/genders/uuid
GET Registrations/Titles	GET Contact-Management/titles

Reminders Service

v2 API	v3 Equivilent
Sigma API's	To Do We are evaluating the Sigma strategy for data extraction jobs, this will be added to our backlog.
Delta API's for Clients, Patients and Clinical History	For Clients see previously listed API's for Contact and Accounts. These allow queries using modified date ranges. For Patients, see previously listed API's for Patients. These allow queries using modified date ranges. For Clinical History, see previously listed API's for Clinical. These allow queries using modified date ranges. For Appointments, see previously listed API's for Calendar. These allow queries using modified date ranges.
GET Reminder/Code Details	For Formulary, see previously listed API's for Formulary. These allow queries using modified date ranges.