Generate clinical note
Generates a clinical note by intelligently filling a structured template with information extracted from a raw text (stt, vtt, plain-text,…) transcription.
Below we will describe the entire process that allows the successful completion of note generation.
Request description
Remember: you can see the URL to consume this API in the Introduction section.
Header
{
"Content-Type": "application/json",
"Authorization": "Bearer <accessToken>"
}
Authorization: We'll pass the token obtained during the authentication process. You can reuse the generated tokens, as they have a 2-hour lifespan. Review this page: Credentials
To set the API version on a specific request, you can add a specific header named X-Invox-Medical-Api-Version with the value of the version you are targeting:
X-Invox-Medical-Api-Version: 2025-11-01
Payload structure
type GenerateReportPayloadType = {
template: IAPITemplate; // Template usded to generate the report
transcription: string; // Transcription used as input to the report
};
export interface IAPITemplate {
id: string;
template_name: string;
template_description: string;
template_language: string;
fields: APITemplateField[];
}
export interface APITemplateField {
id: string;
name: string;
description: string;
type: "string" | "number" | "array" | "boolean" | "enum";
enumerableOptions?: string[];
context?: string;
history?: IFormattedField[];
value: string | string[] | number | boolean;
}
For more details related to the template structure, using the following link: JSON Schema
Responses
Correct response
Successful request
Describe the characteristics of a satisfactory response
200
Response example:
{
"isSuccessRequest": true,
"templateFields": [
{
"id": "mock-id",
"value": "mock-value",
"name": "mock field name",
"type": "string"
}
]
}
type GenerateReportResponseType = {
isSuccessRequest: boolean;
templateFields: ReportField[];
};
type ReportField = {
id: string;
value: string | string[] | number | boolean;
name: string;
type: "string" | "number" | "array" | "boolean" | "enum";
};
Wrong responses
Unauthorized request
Describes the response when the request is not authorized
401
Response body
type GenerateReportResponseType = {
messsage: string;
};
Forbidden request
Describes the response when the API Key is not allowed to consume this service
403
Response body
type GenerateReportResponseType = {
messsage: string;
errorType: string;
};
GENERATE-REPORTBad request
Describe the features of a bad request
400
Response body
type GenerateReportResponseType = {
messsage: string
errorType: GENERATE_REPORT_ERROR_TYPE
}
enum GENERATE_REPORT_ERROR_TYPE {
INVALID_LANGUAGE= 'invalidLanguage'
INVALID_TRANSCRIPTION = 'invalidTranscription',
EMPTY_TRANSCRIPTION = 'emptyTranscription',
INVALID_TEMPLATE_NAME_LENGTH = 'invalidTemplateNameLength', // Max: 64 Characters
INVALID_TEMPLATE_DESCRIPTION_LENGTH= 'invalidTemplateDescriptionLength', // Max: 256 Charachers
EMPTY_TEMPLATE_FIELDS= 'emptyTemplateFields',
ALL_FIELDS_MUST_HAVE_TYPE= 'allFieldsMustHaveType',
FIELDS_WITH_INVALID_TYPE= 'FIELDS_WITH_INVALID_TYPE',
ALL_FIELDS_MUST_HAVE_ID_AND_NAME= 'allFieldsMustHaveIdAndName',
ALL_IDS_MUST_BE_UNIQUE= 'allIdsMustBeUnique',
ENUMERABLE_OPTIONS_ARE_MISSING_OR_EMPTY_FOR_ENUM= 'enumerableOptionsAreMissingOrEmptyForEnum',
ERROR_GENERATING_MEDICAL_REPORT='errorGeneratingMedicalReport'
}