Clients & Patients

This guide explains how to work with client (owner) and patient (animal) data through the Provet Cloud REST API.

In Provet Cloud, a client is the owner or guardian of one or more animals. A patient is the animal being treated. Clients and patients are separate resources: a client can have multiple patients, but each patient belongs to exactly one client. Both resources support full create, read, update, and archive operations via the REST API.

Fetching Clients

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

Use query parameters to filter the client list:

Parameter	Example	Description
`firstname__icontains`	`firstname__icontains=john`	Case-insensitive partial match on first name
`lastname__icontains`	`lastname__icontains=smith`	Case-insensitive partial match on last name
`organization_name__icontains`	`organization_name__icontains=farm`	Partial match on company/organization name
`email__is`	`email__is=john@example.com`	Exact match on email address
`phonenumbers__icontains`	`phonenumbers__icontains=+358`	Partial match on any phone number
`archived__is`	`archived__is=false`	Exclude archived clients
`has_alive_patients__is`	`has_alive_patients__is=true`	Only clients with at least one living patient
`modified__gte`	`modified__gte=2024-03-01T00:00:00`	Records changed since this timestamp (use for delta sync)

Searching by name across individual and corporate clients:

The default behaviour combines filters with AND logic. To search across firstname, lastname, and organization_name simultaneously with OR logic — useful when you don’t know whether a client is a person or a company — add filter_type=or:

GET /api/0.1/client/?firstname__icontains=hill&filter_type=or

This returns any client whose first name, last name, or organisation name contains “hill”.

Creating a Client

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

Request Body Example:

{
    "firstname": "John",
    "lastname": "Smith",
    "email": "john.smith@example.com",
    "country": "GB",
    "customer_type": 0
}

Customer type values:

Value	Description
0	Private person
1	Company
2	EU Company
3	Charitable organization
4	UK charity

Note

The country field uses ISO 3166-1 alpha-2 codes (e.g., FI, GB, US, NO).

Phone numbers are not part of the client record itself — they are created as separate records linked to the client. See the Phone Numbers section below.

Updating a Client

API endpoint: PATCH https://provetcloud.com/<provet_id>/api/0.1/client/<id>/

Only include the fields you want to change. Example — updating the email address and disabling SMS:

{
    "email": "new.email@example.com",
    "no_sms": true
}

Setting no_sms=true or no_email=true prevents Provet from sending automated messages to this client.

Fetching Patients

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

Commonly used filters:

Parameter	Example	Description
`client__is`	`client__is=456`	All patients belonging to a specific client
`name__icontains`	`name__icontains=max`	Case-insensitive partial match on patient name
`microchip__is`	`microchip__is=900123456789012`	Exact microchip number lookup
`species__is`	`species__is=15461002`	Filter by species code — numeric ID from `GET /api/0.1/codelist/species/`
`archived__is`	`archived__is=false`	Exclude archived patients
`deceased__is_null`	`deceased__is_null=true`	Only living (non-deceased) patients
`date_of_birth__gte`	`date_of_birth__gte=2020-01-01`	Patients born on or after this date
`modified__gte`	`modified__gte=2024-03-01T00:00:00`	Records changed since this timestamp

Example — fetch all living, non-archived patients for a specific client:

GET /api/0.1/patient/?client__is=456&archived__is=false&deceased__is_null=true

Creating a Patient

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

Request Body Example:

{
    "client": "https://provetcloud.com/<provet_id>/api/0.1/client/456/",
    "name": "Max",
    "species": 15461002,
    "breed": 13689002,
    "gender": "Male",
    "date_of_birth": "2020-06-15"
}

Note

species and breed accept a numeric code — the id field from the codelist response. Retrieve the list of valid species codes from GET /api/0.1/codelist/species/ and valid breed codes from GET /api/0.1/codelist/breeds/. Use the id field from each result as the value. Codes are installation-specific and may differ between Provet Cloud environments.

The species field in the response returns the human-readable display name (e.g. "Dog (Canine - Domestic)"); to get the numeric code back, read the species_code field instead.

Gender values:

Value	Notes
`Male`
`Female`
`Male, neutered`
`Female, neutered`
`Unknown`
`Gelding`	Equine only
`Mare`	Equine only
`Stallion`	Equine only

Example response:

{
    "id": 2130,
    "url": "https://provetcloud.com/4/api/0.1/patient/2130/",
    "client": "https://provetcloud.com/4/api/0.1/client/218/",
    "name": "Fenton",
    "official_name": "",
    "species": "Dog (Canine - Domestic)",
    "breed": "None",
    "gender": "Female",
    "weight": null,
    "date_of_birth": null,
    "deceased": null,
    "microchip": null,
    "archived": false,
    "home_department": null,
    "created": "2021-11-10T15:45:50.179386+02:00",
    "modified": "2021-11-10T15:45:50.179414+02:00",
    "tags_rel": [],
    "fields_rel": []
}

Updating a Patient

API endpoint: PATCH https://provetcloud.com/<provet_id>/api/0.1/patient/<id>/

Example — recording a microchip and current weight:

{
    "microchip": "900123456789012",
    "weight": "32.5"
}

To mark a patient as deceased, set the deceased field to a date:

{
    "deceased": "2024-03-20"
}

To reactivate a patient that was incorrectly marked as deceased, set deceased to null.

Custom Fields

Custom fields allow clinics to store additional data on clients and patients beyond the standard fields. The available fields differ between Provet installations.

Discovering Available Fields

GET /api/0.1/custom_fields/

Returns all custom field definitions configured for this Provet instance.

Key response fields:

Field	Description
`id`	The field ID — used when writing values
`name`	Human-readable label
`field_type`	Data type of the field (text, number, date, select, etc.)
`content_type`	Which model this field applies to (client or patient)

Reading Custom Field Values

Custom field values are always included in the standard client and patient response as a fields_rel array. Each entry contains:

Field	Description
`id`	ID of this value record
`field_id`	ID of the custom field definition
`label`	Human-readable field name
`value`	The stored value

If fields_rel returns an empty list, it means either no custom fields have been configured on the instance, or no values have been set for that record yet.

You can also fetch custom field values from the dedicated nested endpoints:

GET /api/0.1/client/<id>/custom_field_values/

GET /api/0.1/patient/<id>/custom_field_values/

Writing Custom Field Values

Include the fields_rel array in a create or update request body:

{
    "firstname": "John",
    "lastname": "Smith",
    "fields_rel": [
        {
            "field_id": 42,
            "value": "Referred by Dr. Brown"
        }
    ]
}

For select or multi-select fields, pass value as a list of option objects:

{
    "fields_rel": [
        {
            "field_id": 55,
            "value": [
                {"id": 101, "name": "Option A"},
                {"id": 102, "name": "Option B"}
            ]
        }
    ]
}

You can also create or update values via the nested endpoint:

POST /api/0.1/client/<id>/custom_field_values/

Note

If a custom field value already exists for that field on that record, posting to the nested endpoint will update the existing value rather than returning a duplicate error.

Phone Numbers

Phone numbers are stored as separate records linked to a client, not as fields on the client record itself.

Add a phone number after creating the client:

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

{
    "client": "https://provetcloud.com/<provet_id>/api/0.1/client/456/",
    "phone_number": "+441234567890",
    "type_code": 1
}

Phone type values:

Value	Description
0	Landline
1	Mobile

To list all phone numbers for a client:

GET /api/0.1/phonenumber/?client__is=456

Bulk Patient Creation

To create multiple patients in a single request, use the bulk endpoint:

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

The request body is an array of patient objects using the same fields as the standard create endpoint.

Add ?force_push=true to enable partial success mode: patients that pass validation are created even if others in the batch fail.

Response status codes:

Status	Meaning
201	All patients created successfully
207	Partial success — check response for which records failed
400	All records failed validation

Recommended Sync Pattern

This section describes a practical approach for keeping an external system in sync with Provet client and patient data.

Step 1: Poll for changed clients

GET /api/0.1/client/?modified__gte=<last_sync_timestamp>

Store the current timestamp before each sync run and use it as modified__gte on the next run. This returns only records that changed since your last sync.

Step 2: Fetch patients for changed clients

For each changed client, fetch their patients:

GET /api/0.1/patient/?client__is=<client_id>&modified__gte=<last_sync_timestamp>

Alternatively, poll patients independently on the same modified timestamp:

GET /api/0.1/patient/?modified__gte=<last_sync_timestamp>

Step 3: Handle archived records

Records are never hard-deleted via the API. When a client or patient is removed from active use in Provet, archived is set to true. Treat archived=true as the soft-delete signal in your external system.

Step 4: Sync custom fields if needed

If your integration needs custom field values, fetch them via the nested endpoint for each record:

GET /api/0.1/client/<id>/custom_field_values/

Note

Consider using webhooks for client and patient update events to avoid constant polling. Webhooks notify your system immediately when a record changes. See Webhooks for configuration details and List of Webhook Triggers for the list of available events.