Generate report

Generates a clinical report 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 report generation.

Request description

Endpoint: /api/v1/generate-report
Method: POST

Remember: you can see the URL to consume this API in the Introduction section.

{
  "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

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"
    }
  ]
}
Response structure
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
}

Remember that to consume this service, the API Key must have the permission: GENERATE-REPORT

Bad 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'
}

Remember that the valid languages are: es_ES, ca_ES, pt_PT, pt_BR, en_GB, en_US
Remember that the valid types are: string, number, boolean, array, enum
Table of Contents