consultations

Create a new consultation

Creates a consultation owned by the authenticated user and returns a presigned URL for uploading its first audio recording.

With externalId, the call is an upsert: if an active consultation in the workspace already has that externalId, it is returned unchanged (with a fresh upload URL) and nothing is created. Without externalId or clientConsultationId, every call creates a new consultation, so retrying a request that timed out can create duplicates. With clientConsultationId, retries return the consultation the first request created, and an ID that belongs to another consultation returns 409.

Creating a consultation does not record or transcribe anything. Next steps: PUT audio to recordingUploadUrl, then call POST .../transcriptions/start. The first consultation in a workspace that is waiting to start its free trial starts the trial.

post/workspaces/{workspaceId}/consultations

Request

Base URL
https://vetnio.com/api/v2
URL
https://vetnio.com/api/v2/workspaces/{workspaceId}/consultations
Auth
HTTP bearer

Path parameters

workspaceIdstring required

Identifier of the clinic (workspace), as returned by GET /workspaces. The key's user must be a member of the clinic, or an admin of the organization it belongs to.

Example:furunculotic-loud-chihuahua

Request body

clientConsultationIdstring uuid

Client-generated UUID that makes creation idempotent. Retrying with the same ID returns the consultation the original request created for the same workspace and user; an ID that belongs to any other consultation returns 409. With externalId, an existing consultation for that externalId still takes precedence, and the ID is used when a new consultation is created.

namestring required

Display name for the consultation, typically the patient's name and the reason for the visit. Free text; not validated (an empty string is accepted).

recordingLanguageCodestring required

Language spoken in the consultation, as a lowercase ISO 639 code such as en, sv or de, optionally followed by subtags (pt-BR). Stored on the consultation and embedded in the returned upload URL's recording ID, which sets the transcription language of that first recording. A value that is not a two- or three-letter code with optional subtags returns 400; use a supported language code.

externalIdstring

Identifier of the matching visit in your practice-management system. If an active (not archived or deleted) consultation in this workspace already has this externalId, that consultation is returned unchanged instead of creating a new one, whoever created it; name and recordingLanguageCode are then not applied. When externalId is set, clinicalNoteTemplateId is ignored, even if a new consultation is created.

clinicalNoteTemplateIdstring

ID of the clinical note template to use when generating this consultation's note. An unknown ID, or auto, is ignored and the consultation is created without a template. If the template is linked to a JSON template, that structured template is bound as well. Ignored when externalId is provided.

Example request

{
  "clientConsultationId": "3f2b8c1e-5d4a-4e7b-9c6f-1a2b3c4d5e6f",
  "name": "Bella - vaccination",
  "recordingLanguageCode": "en",
  "externalId": "123456",
  "clinicalNoteTemplateId": "6a4dd7d0-0fe8-4f73-8e05-8898748da1ce"
}

Response

The created (or matched) consultation with an upload URL for its first recording.

consultationIdstring required

ID of the consultation that was created, or of the existing consultation returned because its externalId matched.

recordingUploadUrlstring uri required

Presigned URL for uploading the first audio recording with PUT (raw bytes as the body), valid for 24 hours. It behaves exactly like a URL from GET .../recording-upload-url: its recording ID is fixed now, so upload promptly and fetch a new URL for each further segment.

Example response

{
  "consultationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recordingUploadUrl": "https://example-bucket.s3.eu-central-1.amazonaws.com/recordings/furunculotic-loud-chihuahua/a1b2c3d4-e5f6-7890-abcd-ef1234567890/1726302600000-en?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&X-Amz-Signature=...",
  "consultation": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Bella - vaccination",
    "createdAt": "2026-09-14T08:30:00.000Z",
    "externalId": "123456"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.