Consultations

A consultation is one visit: a vet examines an animal, talks with the owner, and Vetnio turns the conversation into a clinical note. The consultation holds everything about that visit, belongs to exactly one clinic (a workspace) and can be linked to one patient. Document a visit end to end walks through the calls in order; this page explains the object and its states.

What a consultation holds

Identifiers

Set externalId when you create the consultation or later with PUT/workspaces/{workspaceId}/consultations/{consultationId}/external-id. Integrations use it to find the consultation again and to export notes back to the practice system.

externalId makes creation idempotent

When you send externalId to POST/workspaces/{workspaceId}/consultations, Vetnio first looks for an active consultation in the same clinic with that value. If it finds one, it returns it unchanged with a fresh upload URL; otherwise it creates a new consultation. Repeating a request with the same externalId and a different name returns the original:

{
  "consultationId": "4b2730b1-3e78-4d82-9114-030a055e8581",
  "recordingUploadUrl": "https://storage.example.com/recordings/demo-north-clinic/4b2730b1-3e78-4d82-9114-030a055e8581/1791130540933-sv?X-Amz-Expires=86400&X-Amz-Signature=…",
  "consultation": {
    "id": "4b2730b1-3e78-4d82-9114-030a055e8581",
    "name": "Bella - lameness left hind",
    "createdAt": "2026-10-04T16:15:36.818Z",
    "recordingDurationInMilliseconds": 0,
    "uploadedRecordingDurationInMilliseconds": 0,
    "isGeneratingClinicalNote": false,
    "isGeneratingCommunication": false,
    "externalId": "pims-appt-58213"
  }
}

Know the edges of this behavior:

• The match is clinic-wide: it can return a consultation that a colleague, another integration or the Vetnio app created.
• A matched consultation keeps its name and language; only the new upload URL uses the requested language.
• clinicalNoteTemplateId is ignored whenever externalId is set, even when a consultation is created. Choose the template when you generate the note.
• Archived consultations and consultations deleted in the Vetnio app are skipped, so after an archive the same externalId creates a new consultation.
• If two active consultations share an externalId, which one is returned is not defined.
• Without externalId, a retried request can create a duplicate unless you send a clientConsultationId.

clientConsultationId makes any creation retry-safe

Generate a UUID, store it, and send it as clientConsultationId; it becomes the new consultation's id. Repeating the request with the same value returns the consultation the first request created for the same user and clinic, instead of creating another. If the value is the ID of any other consultation, or the consultation it created has since been archived, the call returns 409. Sent together with externalId, a consultation that matches the externalId still wins, and clientConsultationId is only used when a new consultation is created.

Lifecycle

Until it is archived, a consultation stays open. You can upload more audio after a note exists: the new segments are transcribed on the next start, and the note can be regenerated or updated from the longer transcript.

Status fields to poll

GET/workspaces/{workspaceId}/consultations/{consultationId} is the status endpoint. It is read-only and fast enough to poll every few seconds.

transcriptionFailureReason is null unless the status is failed:

The other fields you will use:

• isReadyForGeneration is true when no segment is waiting for transcription and there is something to write from: transcript text, a text partial transcription or an analyzed uploaded file. Permanently failed segments do not block it, and it is always false for archived consultations.
• isGeneratingClinicalNote and isGeneratingCommunication are true while Vetnio writes that record.
• recordingDurationInMilliseconds is the total uploaded audio; recordingDurationInMillisecondsExcludingSilence leaves out stretches quieter than -40 dB. Both update shortly after each upload, not at once, and are 0 until the first upload is processed. Uploaded audio counts toward the clinic's recorded usage.

Visibility and permissions

Any member of a clinic, and any admin of its organization, can read and change any consultation in it by ID, whoever created it. A consultation that does not exist, belongs to another clinic or is outside your access returns 404 Consultation not found, never 403.

The list is narrower: GET/workspaces/{workspaceId}/consultations returns only consultations created by the key's user, even when the clinic lets members see each other's consultations in the app. To enumerate a whole clinic, a clinic admin uses GET/workspaces/{workspaceId}/data-export/consultations, described in Export clinical data.

Listing and searching

• currentPage starts at 1; a value below 1 causes a 500. consultationsPerPage defaults to 10 with no maximum, but every row checks storage for saved records, so keep pages at 50 or fewer.
• Results are newest first, offset-paginated (see Pagination). Follow-up visits linked in a timeline are returned together and count as one entry toward the page size and count, so a page can hold more items than requested.
• searchQuery is a case-insensitive substring match on the name, the clinical note text, externalId and the linked patient's name or identifier. To look up an externalId, search for it and compare exactly.
• Archived consultations and consultations deleted in the app are excluded.

Renaming and additional info

• PATCH/workspaces/{workspaceId}/consultations/{consultationId} takes { "name": "…" } and returns {}. Only the name can change.
• PUT/workspaces/{workspaceId}/consultations/{consultationId}/additional-info stores 1 to 10,000 characters of context, replacing any earlier value; it can be overwritten but not cleared. GET/workspaces/{workspaceId}/consultations/{consultationId}/additional-info returns 404 until something is saved. Additional info feeds every record generation but is not part of the transcript.

Archiving

DELETE/workspaces/{workspaceId}/consultations/{consultationId} archives the consultation and returns { "success": true }. Nothing is erased: recordings, transcript, uploaded files and records are kept, and the clinic's audio-retention policy keeps running on its normal schedule.

An archived consultation is read-only. Every write, including a second DELETE, returns 403 with a reason you can branch on:

{
  "message": "You cannot modify this consultation",
  "code": "FORBIDDEN",
  "data": {
    "code": "FORBIDDEN",
    "httpStatus": 403,
    "path": "consultations.delete",
    "zodError": null,
    "reason": "archived_consultation"
  }
}

Archived consultations still answer GET/workspaces/{workspaceId}/consultations/{consultationId}, the transcript, additional info and records with 200, but nothing in those responses says the consultation is archived. They disappear from the list and stay in the admin export list. GET/workspaces/{workspaceId}/consultations/{consultationId}/partial-transcriptions returns 404 for them.

Users restore archived consultations in the Vetnio app (Consultations → Archived). The API cannot restore or permanently erase a consultation. A consultation deleted in the Vetnio app behaves like an archived one for the API, with reason: "hidden_consultation".

Common pitfalls

• Uploading audio does not start transcription. Call POST/workspaces/{workspaceId}/consultations/{consultationId}/transcriptions/start after your uploads; until then the status stays processing.
• Segments uploaded late are never transcribed. A segment whose upload URL was issued before an already-transcribed segment is skipped. Fetch each GET/workspaces/{workspaceId}/consultations/{consultationId}/recording-upload-url right before uploading that segment, and upload in order.
• failed does not mean there is no transcript. One segment was lost; the rest is usable.
• A 403 with reason: "archived_consultation" is final. Retrying will not help; create a new consultation if the visit continues.