Understanding Separations

Separation Entities

There are 4 different types of separation entities within ezyVet, each representing different aspects depending on the structure of the site. Each separation is referenced by other records within ezyVet using its ID. The ID is a static value within the site and cannot be changed.

Database

• The topmost level of the hierarchy.
• This separation will always have an ID of 1.
• separation_type: "Department"

Business

• Alias for "Business Unit".
• Represents a clinic in a multi-tenant site where the customer wants to separate finances between clinics.
• separation_type: "Hospital"
• Returns a derived_hospital_uid field identifying the hospital record associated with this business unit.

Division

• Represents a department within a business (e.g., General, Surgery, Emergency).
• Can represent a clinic in a multi-tenant site where the customer doesn’t care about separating finances.
• separation_type: "Department"
• Returns a hospital_uid field identifying the hospital this division belongs to.

Location

• Represents a physical stock location.
• Usually a child of a business or division.
• Would only be set as a child of a database if the site is a single-tenant structure (one clinic).
• separation_type: "" (empty — locations have no sub-classification)
• Returns a hospital_uid field identifying the hospital this location belongs to.

Why it’s important to understand separations

When creating or updating records in ezyVet, if the appropriate separation is not referenced, the records will be linked to incorrect areas within the site. This can lead to:

• Inaccurate clinical records.
• Duplication of records.
• Incorrect financial reporting.
• Inaccurate stock counts and inventory reporting.
• Inaccurate KPIs relating to sales, commission, revenue, growth, etc.

Ultimately, this can cause the database to become cluttered, inaccurate, and inefficient, leading to poor customer impressions and additional administrative work.

Example Diagrams

• The below diagram is an example of a multi-tenant site structure with separated finances, which is evident by the two business units.
  • Note that both departments and business units can be parents of stock locations.
• The below diagram is an example of a single-tenant site structure, which is evident by the absence of business units and that the database is a parent of a stock location. This is because the database represents the clinic.

How to get a list of separations on a site

Make a GET request to the v2/separation endpoint.

Example Separation Response Object

The example below shows one separation of each type. Note which fields appear conditionally depending on type.

{
  "items": [
    {
      "separation": {
        "id": 1,
        "uid": "ownershipSeparation_d01oHZu5uCuy0VdOgAn23",
        "created_at": 1419765339,
        "modified_at": 1747002038,
        "active": true,
        "name": "Galaxy Vets",
        "type": "database",
        "parent": null,
        "child": 16,
        "separation_type": "Department",
        "contact_id": 3,
        "contact_uid": "contact_lg1jdmDnObgYMCjwG2cuD"
      }
    },
    {
      "separation": {
        "id": 16,
        "uid": "ownershipSeparation_9V0WG0BiBouk5tB70qafg",
        "created_at": 1747002038,
        "modified_at": 1774561844,
        "active": true,
        "name": "Death Star Vets BU",
        "type": "business",
        "parent": 1,
        "child": 3,
        "separation_type": "Hospital",
        "derived_hospital_uid": "hospital_tGRMQ8HgPJpEDSRYNJb8E",
        "contact_id": 3,
        "contact_uid": "contact_lg1jdmDnObgYMCjwG2cuD"
      }
    },
    {
      "separation": {
        "id": 4,
        "uid": "ownershipSeparation_cAl0DAnmH0C1EqVw0souz",
        "created_at": 1641839727,
        "modified_at": 1756258352,
        "active": true,
        "name": "Death Star Emergency",
        "type": "division",
        "parent": 16,
        "child": 5,
        "separation_type": "Department",
        "hospital_uid": "hospital_tGRMQ8HgPJpEDSRYNJb8E",
        "contact_id": 3,
        "contact_uid": "contact_lg1jdmDnObgYMCjwG2cuD"
      }
    },
    {
      "separation": {
        "id": 5,
        "uid": "ownershipSeparation_9K8oZgeaLT0AEctz3KtwC",
        "created_at": 1571345127,
        "modified_at": 1756258352,
        "active": true,
        "name": "Death Star Emergency Inventory",
        "type": "location",
        "parent": 4,
        "child": null,
        "separation_type": "",
        "hospital_uid": "hospital_tGRMQ8HgPJpEDSRYNJb8E",
        "contact_id": 3,
        "contact_uid": "contact_lg1jdmDnObgYMCjwG2cuD"
      }
    }
  ]
}

Building the hierarchy from the separation endpoint

With the response of the call made to the v2/separation endpoint, you can quickly build out the tree diagram/hierarchy using the id and parent fields.

Below is a hierarchy based on the above response:

Conditional fields by separation type

Two fields in the separation response are conditional — they are only present on certain separation types.

Field	Type	Present on
hospital_uid	string	division, location
derived_hospital_uid	string	business

hospital_uid — The UID of the hospital record that the division or location belongs to. Use this to associate a division or stock location back to its hospital without needing to traverse the full hierarchy.

derived_hospital_uid — The UID of the hospital record derived from a business unit. Use this when you need to map a business unit to its corresponding hospital, for example when working with the hospital endpoint.

References to separations in other endpoints

Separations will be referenced in the response body of other endpoints in one of two ways:

ownership_id

• The most common field referencing the ID of a separation.
• Can be one of:
  • Database
  • Business
  • Division
• Note: If you’re a diagnostic supplier utilizing the SDI framework, this field is represented as OwnershipId.

location_id

• Most commonly referenced in stock-related records (e.g., invoice line items, receive invoice line items).
• Indicates to which stock location the item was added or removed.
• Relates only to:
  • Location

Record types tied to a specific separation

• Contacts
  • Pet parent records are tied to the separation that represents their local clinic.
• Invoices / Receive Invoices
  • Financial information needs to be isolated to a single business (unit) for financial reporting.
• Invoice Line Items / Receive Invoice Line Items
  • Need to be isolated to a location, as they represent stock leaving/entering a physical stock location.
• Resources
  • A bookable, localized reflection of a user.
  • Example: A user (Dr. Bloggs) takes bookings in Surgery and General, resulting in 2 resources:
    • Dr. Bloggs (Surgery)
    • Dr. Bloggs (General)
• Payments
  • Financial information needs to be isolated to a single business (unit) for financial reporting.
• Clinical Records
  • Represents a pet’s visit, so should be allocated to the appropriate business unit/department.

Examples of record types that inherit a separation from a linked record

• Appointments
  • The separation is inherited from the linked resource.
  • Query the v2/appointment endpoint.
  • Query the v2/resource endpoint while referencing the sales_resource field from the appointment endpoint’s response.
  • Note the ownership_id field: This is the separation linked to the resource and thus the appointment.
• Diagnostic Requests
  • The separation is inherited from the linked clinical record.
  • Query the v1/diagnosticrequest endpoint.
  • Note the ownership_id field: This is the separation linked to the clinical record and thus the diagnostic request.
  • If you’re a diagnostic supplier, take the body of the diagnostic request sent to your endpoint.
• Animals
  • The separation is inherited from the linked contact (pet parent).

Separations and Standard Product Supplier Integrations (SPSI)

If you’re a product supplier utilizing the ezyVet SPSI framework, separations play a key part in ensuring the integration works correctly.

When to use separations?

• When creating a receive invoice.
• When mapping separation names to IDs/UIDs in your third-party system.
• When returning product pricing.

Where do I get the relevant values?

• From the purchase order.
• From the purchase order line item.
• From the query ezyVet sends to your product endpoint.

Why is this so important?

• The ownership_id field in the purchase order and receive invoice main body dictates which business unit or department will be impacted.
• The location_id field in the PO line item and RI line item dictates which physical stock location is impacted.

Mapping Example

Note:

• The ownership_id (13) field in the main body of the PO is the same as the ownership_id (13) in the main body of the receive invoice.
• The ownership_id (14) field in the purchase_order_item_list is reflected as location_id (14) in the receive invoice line item list.

partner-endpoint/purchase-order
{
  "purchaseorder": {
    "id": "232",
    "active": "1",
    "created_at": "1727406805",
    "modified_at": "1727406808",
    "date": "1727326800",
    "shipping_address_id": "8685",
    "comments": "",
    "freight": "0",
    "freight_tax": "0",
    "tax": "10.28",
    "total": "78.83",
    "client_id": "",
    "supplier_id": "187",
    "status": "Approved",
    "supplier_order_number": "",
    "supplier_account_number": "",
    "purchase_order_number": "1130225",
    "ownership_id": "13",
    "purchase_order_item_list": [
      {
        "id": "374",
        "product_id": "2689",
        "supplier_code": "200402",
        "outers": "1",
        "units_per_outer": "1",
        "price_per_unit": "68.55",
        "tax_per_unit": "10.2825",
        "quantity": "1",
        "total": "68.55",
        "total_tax": "10.28",
        "ownership_id": "14"
      }
    ]
  }
}

v2/receiveinvoice
{ 
  "invoice_number": "510576", 
  "date": 1724594400, 
  "due_date": 1724594400, 
  "ownership_id": "13", 
  "line_item": [
     { 
        "quantity": "1.0", 
        "price": "68.55", 
        "tax": "18.5660", 
        "supplier_code": "2689", 
        "location_id": "14", 
        "purchase_order_item_id": "374" 
      } 
  ] 
}