Consultations

This guide explains how to create and manage consultations through the Provet Cloud REST API, including adding clinical items, diagnoses, and notes.

A consultation represents a clinical visit or patient encounter. Items such as medicines, procedures, supplies, and foods are not part of the consultation record itself — they are added as separate sub-resources after the consultation is created. Consultations move through a defined set of statuses before being finalized and invoiced.

Consultation Lifecycle

Value	Status	Description
0	Admitted	Initial state after the patient is checked in
8	In Progress	Consultation is actively under way
5	Ready for Discharge	Clinical work done, awaiting discharge
6	Discharged	Patient has been discharged
7	Invoicing	Consultation is in the invoicing stage
9	Invoice Paid	The consultation invoice has been fully paid
10	Finalized	Consultation complete and invoiced
11	Draft	Preliminary/unsaved state

Note

The status field is read-only on create. Use the update_status endpoint to move a consultation through its lifecycle. See Managing Consultation Status below.

Creating a Consultation

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/consultation/

Request Body Example:

{
    "client": "https://provetcloud.com/<provet_id>/api/0.1/client/456/",
    "patients": [
        "https://provetcloud.com/<provet_id>/api/0.1/patient/789/"
    ],
    "started": "2024-03-20T09:00:00",
    "finished": "2024-03-20T10:00:00",
    "complaint": "Limping on right front leg",
    "type": 1
}

supervising_veterinarian is optional and defaults to the authenticated user. department is optional and inferred from the patient’s home department if not provided.

Consultation type values:

Value	Description
0	Inpatient
1	Outpatient
2	Home call
3	Farm visit
4	Boarding
5	Pet service

Note

“Please update communication preferences” error

If the API returns {"client": "Please update communication preferences."} when creating a consultation, the error is about the client record, not the consultation itself. It occurs when the clinic has the communication preferences feature enabled and the selected client does not have valid preferences on file.

To resolve: ask the clinic to update the client’s communication preferences in the Provet Cloud UI, or ask the clinic admin to check the enable_communication_preferences department setting. This is not an issue with your API request.

Fetching and Filtering Consultations

API endpoint: https://provetcloud.com/<provet_id>/api/0.1/consultation/

Parameter	Example	Description
`status__is`	`status__is=8`	Filter by status value
`client__is`	`client__is=456`	All consultations for a client
`patients__is`	`patients__is=789`	All consultations for a patient
`department__is`	`department__is=1`	Filter by department
`started__gte`	`started__gte=2024-03-01`	Consultations started on or after this date
`started__lte`	`started__lte=2024-03-31`	Consultations started on or before this date
`modified__gte`	`modified__gte=2024-03-20T00:00:00`	Records changed since this timestamp (delta sync)
`supervising_veterinarian__is`	`supervising_veterinarian__is=10`	Filter by vet

Example — fetch all finalized consultations modified since a timestamp:

GET /api/0.1/consultation/?status__is=10&modified__gte=2024-03-20T00:00:00

Example response for a single consultation (GET /api/0.1/consultation/338/):

{
    "url": "https://provetcloud.com/4/api/0.1/consultation/338/",
    "client": "https://provetcloud.com/4/api/0.1/client/1/",
    "patients": [
        "https://provetcloud.com/4/api/0.1/patient/1/"
    ],
    "complaint": "Test consultation",
    "admitted_time": "2017-05-18T10:35:00Z",
    "first_entry": null,
    "started": "2017-05-18T10:35:00Z",
    "finished": null,
    "ended": null,
    "status": 8,
    "type": 0,
    "invoice": "https://provetcloud.com/4/api/0.1/invoice/609/",
    "supervising_veterinarian": "https://provetcloud.com/4/api/0.1/user/1/",
    "department": "https://provetcloud.com/4/api/0.1/department/1/",
    "consultation_items": [
        "https://provetcloud.com/4/api/0.1/consultationitem/4558/",
        "https://provetcloud.com/4/api/0.1/consultationitem/4559/",
        "https://provetcloud.com/4/api/0.1/consultationitem/4560/"
    ],
    "reporting_dimension_1": null,
    "reporting_dimension_2": null
}

Adding Items to a Consultation

Medicines, procedures, supplies, and foods are added via sub-resource endpoints nested under the consultation. All follow the same URL pattern:

POST /api/0.1/consultation/<id>/<item_type>/

Each item links to your organisation’s master data via the item field. Retrieve the item URL from the generic GET /api/0.1/item/ endpoint — the url field on each result is the value to pass as item.

Common required fields for all item types:

Field	Description
`consultation`	URL of the parent consultation
`patients`	Array of patient URLs receiving the item
`item`	URL of the item — use the generic `/api/0.1/item/<id>/` URL, not type-specific URLs
`quantity`	Numeric quantity
`vat_percentage`	VAT rate as a decimal (e.g. `24.0`)

Adding a Medicine

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/consultation/<id>/medicines/

{
    "consultation": "https://provetcloud.com/<provet_id>/api/0.1/consultation/123/",
    "patients": ["https://provetcloud.com/<provet_id>/api/0.1/patient/789/"],
    "item": "https://provetcloud.com/<provet_id>/api/0.1/item/55/",
    "quantity": "1.000",
    "vat_percentage": "14.0",
    "usage_type": 1,
    "usage_size": 1,
    "instructions": "Give once daily with food"
}

Usage type values:

Value	Description
1	Administered (given by the clinic)
2	Dispensed (given to the owner)
3	Prescribed
4	Home delivery

Usage size values:

Value	Description
1	Package
2	Dosage units

Adding a Procedure

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/consultation/<id>/procedures/

{
    "consultation": "https://provetcloud.com/<provet_id>/api/0.1/consultation/123/",
    "patients": ["https://provetcloud.com/<provet_id>/api/0.1/patient/789/"],
    "item": "https://provetcloud.com/<provet_id>/api/0.1/item/12/",
    "quantity": "1.000",
    "vat_percentage": "24.0"
}

Adding a Supply

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/consultation/<id>/supplies/

{
    "consultation": "https://provetcloud.com/<provet_id>/api/0.1/consultation/123/",
    "patients": ["https://provetcloud.com/<provet_id>/api/0.1/patient/789/"],
    "item": "https://provetcloud.com/<provet_id>/api/0.1/item/33/",
    "quantity": "2.000",
    "vat_percentage": "24.0",
    "usage_type": 1,
    "usage_size": 1
}

Adding Food

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/consultation/<id>/foods/

{
    "consultation": "https://provetcloud.com/<provet_id>/api/0.1/consultation/123/",
    "patients": ["https://provetcloud.com/<provet_id>/api/0.1/patient/789/"],
    "item": "https://provetcloud.com/<provet_id>/api/0.1/item/7/",
    "quantity": "1.000",
    "vat_percentage": "14.0"
}

Note

For farm or herd consultations, add ?no_multiplier=true to the request URL to prevent the herd size multiplier from being applied to quantities.

Fetching Items

Retrieve all items for a consultation using the same sub-endpoints:

GET /api/0.1/consultation/<id>/medicines/

GET /api/0.1/consultation/<id>/procedures/

GET /api/0.1/consultation/<id>/supplies/

GET /api/0.1/consultation/<id>/foods/

To get a flat list of all item types together, use the read-only consultationitem/ endpoint filtered by type:

GET /api/0.1/consultationitem/?type_code=2

Item type codes:

Value	Description
1	Procedure
2	Medicine
3	Supply
4	Food
5	Laboratory analysis
6	Laboratory analysis panel

Adding Diagnoses

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/consultation/<id>/consultationdiagnosis/

{
    "consultation": "https://provetcloud.com/<provet_id>/api/0.1/consultation/123/",
    "patient": "https://provetcloud.com/<provet_id>/api/0.1/patient/789/",
    "diagnosis": 21229002,
    "code": "21229",
    "name": "( Severe ) Combined immunodeficiency disease ( SCID )",
    "category": 0,
    "type": 1
}

The diagnosis, code, and name fields come from the codelist. First fetch the available diagnoses:

GET /api/0.1/codelist/diagnoses/

Each result contains:

Codelist field	Maps to diagnosis field	Notes
`id`	`diagnosis`	Numeric coded ID — pass as an integer
`display_code`	`code`	Human-readable code string — pass as a string
`label`	`name`	Full diagnosis name

code and name are snapshot fields — they are not auto-populated from the diagnosis value and must always be provided explicitly. Storing them ensures the diagnosis record remains accurate even if the codelist entry changes later.

For custom clinic-created diagnoses (not in VeNom/ICD), pass a listitem URL instead of a numeric ID: https://provetcloud.com/<provet_id>/api/0.1/listitem/<id>/.

Category values:

Value	Description
0	Primary
1	Secondary

Type values:

Value	Description
0	Differential
1	Final

Clinical Notes

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/consultation/<id>/consultationnote/

{
    "patient": "https://provetcloud.com/<provet_id>/api/0.1/patient/789/",
    "text": "Patient presented with mild lameness on right forelimb.",
    "type": 0
}

Note type values:

Value	Description
0	Clinical note
1	Anamnesis
2	Preliminary note

Discharge Instructions

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/consultation/<id>/consultationdischargeinstruction/

{
    "patient": "https://provetcloud.com/<provet_id>/api/0.1/patient/789/",
    "text": "Rest for 5 days. Return if limping worsens."
}

Managing Consultation Status

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/consultation/<id>/update_status/

Use this endpoint to move a consultation through its lifecycle. The allowed transitions are:

Admitted → In Progress:

{
    "status": 8
}

In Progress → Finalized:

{
    "status": 10
}

Ready for Discharge → Finalized:

{
    "status": 10
}

Note

Finalizing a consultation triggers invoice creation. Ensure all items, diagnoses, and notes have been recorded before finalizing.

Recommended Sync Pattern

For integrations that consume consultation data — such as laboratory systems, ERP, or reporting tools — use the following approach:

Step 1: Poll for newly finalized consultations

GET /api/0.1/consultation/?status__is=10&modified__gte=<last_sync_timestamp>

Step 2: Fetch clinical items

For each consultation, fetch items by type:

GET /api/0.1/consultation/<id>/medicines/

GET /api/0.1/consultation/<id>/procedures/

GET /api/0.1/consultation/<id>/consultationdiagnosis/

Step 3: Mark consultations as exported

Use the mark_sent action to record that your system has processed the consultation. This sets the external_sent timestamp and lets you filter out already-exported records on the next run:

POST /api/0.1/consultation/<id>/mark_sent/

Request body:

{
    "external_sent": "2024-03-20T12:00:00"
}

On subsequent runs, add external_sent__is_null=true to your filter to skip already-exported consultations.

Note

Webhook events are available for consultation finalization, which removes the need for polling. See Webhooks for configuration details and List of Webhook Triggers for available events.