Skip to main content

Contact Management

Contact is an individual or business of various types, such as staff member, system user and clients (Animal Owners).

Contacts in Merlin?

Contacts exist in Merlin, however you will not see this terminology in the front end, this is a generic term that covers multiple interaction and data points for example, the Clients in Reception (minus account elements), Users in Administration and Practitioners in the Diary.

Contact Child Data​

Within the Contact Domain there are several datapoints for managing all contact data, from the schema you will notice that all child data have their own endpoints providing you granular control such as collecting data in a progressive profile build fashion.

There are endpoints specifically for Clients, others for Practitioners and Users while others can be used across all 3.

Child data currently consists of:

  1. Addresses
  2. Numbers (Mobile, Home, etc)
  3. Email
  4. Data Consent
  5. Practitioner Locations
  6. Practitioner Qualifications

Relationships​

A contact will be referenced across domains, and for different contexts, e.g. appointment will have a contact for Client and another for Practitioner.

The contact contains specific metadata which supports the relationships between these entities such as Contact type, e.g. You cannot add practitioner metadata to a Client.

erDiagram Account { uuid account-uuid } Contact ||--|| Account : Related Contact { uuid contact-uuid uuid default-location-uuid } Contact ||--|| Location : Related Location { uuid location-uuid } Contact ||--o{ Appointment : Related Appointment { uuid account-contact-uuid uuid contact-practitioner-uuid uuid assigned-practitioner-uuid } Contact ||--o{ Availability : Related Availability { uuid practitioner-uuid } Contact ||--o{ Clinical : Related Clinical { uuid contact-practitioner-uuid } Contact ||--o{ Reminder : Related Reminder { uuid contact-uuid } Contact ||--o{ Communications : Related Communications { uuid contact-uuid }
caution

In the current iteration there is a 1:1 relationship between Account and Contact.

This is due the current legacy support, however please plan for a 1:M relationship where 1 Account may have Many Billing accounts.

Practitioners and rooms​

Practitioner and task-list contacts used by the diary are exposed under /practitioners. In Practitioner mode (the default), diary columns are people. In Room mode (beta in selected practices), diary columns can be room contacts, while vets are still modelled as practitioners and referenced as assignees on appointments.

Calendar booking rules, availability fields, and validation by site mode are described in Diary mode (Practitioner and Room) in the calendar domain.

Listing practitioners

  • GET /practitioners and GET /practitioners/{contact-uuid} include practitioner-type-name (for example PRACTITIONER or ROOM).
  • Optional query parameter exclude-rooms=true omits rooms (practitioner-type ROOM) when the integration only needs people (typical pickers on Practitioner mode sites).

Practitioner locations

  • GET /practitioners/locations includes practitioner-type-id and practitioner-type-name per row.
  • exclude-rooms=true applies here as well.

Disciplines

  • GET /practitioners/{contact-uuid}/disciplines returns 404 for rooms (practitioner-type ROOM) and task-list contacts that are not eligible practitioners.
  • POST /practitioners/{contact-uuid}/disciplines/{discipline-uuid} returns 422 when the contact is not a valid practitioner for discipline assignment.
  1. An Account cannot be created without a Contact of the Client Type.
  2. A Contact cannot change Types, e.g. from Practitioner to Client.

Contact Schema​

Please take note of the following points for this domain:

  1. Eligibility can only be applied to tenants that are charities.
  2. Data Consent - Currently data consent can only be recorded to Client Types.

Cross Domain UUID References​

ReferenceDomainResourceNote
communication-type-uuidcommunications/communication-channelsReference for communication preferences to the channels e.g. SMS, email.
communication-channel-uuidcommunications/communication-typesReference for communication perferences to the type of communication e.g. Marketing.

Security Scopes​

The following authorisation scopes are required to access different resources within this domain:

  • contact-mgt:create
  • contact-mgt:read
  • contact-mgt:update
  • contact-mgt:remove
  • contact-mgt:contacts:create
  • contact-mgt:contacts:read
  • contact-mgt:contacts:update
  • contact-mgt:contacts:remove
  • contact-mgt:eligibility:create
  • contact-mgt:eligibility:read
  • contact-mgt:eligibility:update
  • contact-mgt:eligibility:remove
  • contact-mgt:practitioner:create
  • contact-mgt:practitioner:read
  • contact-mgt:practitioner:update
  • contact-mgt:practitioner:remove