{
  "openapi": "3.0.3",
  "info": {
    "title": "Nabla Connect API",
    "description": "Nabla Connect callback API reference.",
    "version": ""
  },
  "paths": {
    "/callback": {
      "post": {
        "summary": "Receive Nabla Connect events",
        "description": "This is the endpoint you need to implement on your server to receive callbacks. This page references the format of all the possible callbacks.",
        "tags": [
          "Nabla Connect"
        ],
        "operationId": "callback",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/callback"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/callback_response"
                }
              }
            },
            "description": "Respond with 200 to acknowledge the handling of this event."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "note_export": {
        "$ref": "#/components/schemas/callback_note_export"
      },
      "uuid": {
        "type": "string",
        "format": "uuid",
        "description": "A unique identifier.",
        "example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6"
      },
      "callback_type": {
        "type": "string",
        "enum": [
          "NOTE_EXPORT",
          "PATIENT_INSTRUCTIONS_EXPORT"
        ]
      },
      "base_callback": {
        "type": "object",
        "properties": {
          "request_uuid": {
            "$ref": "#/components/schemas/uuid",
            "description": "The unique identifier of this webhook event"
          },
          "type": {
            "$ref": "#/components/schemas/callback_type",
            "description": "Type of this event, serves as a discriminator between the different possible webhook types."
          }
        },
        "required": [
          "request_uuid",
          "type"
        ]
      },
      "note_section_type": {
        "type": "string",
        "description": "A category identifying a section of a note.\nThe set of possible categories depend on the template that is used.",
        "example": "CHIEF_COMPLAINT",
        "enum": [
          "CHIEF_COMPLAINT",
          "HISTORY_OF_PRESENT_ILLNESS",
          "PAST_HISTORY",
          "CURRENT_MEDICATIONS",
          "VITALS",
          "IMMUNIZATIONS",
          "ASSESSMENT_AND_PLAN",
          "EXAMINATION",
          "RESULTS",
          "PRESCRIPTIONS",
          "APPOINTMENTS"
        ]
      },
      "note_section_content_text": {
        "type": "object",
        "description": "Plain-text note section content.",
        "required": [
          "type",
          "text"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "TEXT"
            ]
          },
          "text": {
            "type": "string",
            "description": "Content of the note section.",
            "example": "Sleep disorder"
          }
        }
      },
      "icd10_entry_with_hcc_mcc": {
        "type": "object",
        "description": "An ICD-10 entry including HCC and MCC information.",
        "properties": {
          "system": {
            "type": "string",
            "description": "The used coding system, only ICD-10 is supported for now.",
            "enum": [
              "http://hl7.org/fhir/sid/icd-10-cm"
            ]
          },
          "code": {
            "type": "string",
            "example": "G44.8",
            "description": "Code of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry."
          },
          "display": {
            "type": "string",
            "example": "Other specified headache syndromes.",
            "description": "Description of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry."
          },
          "is_hcc": {
            "description": "Indicates if this code maps to a Hierarchical Condition Category (HCC) under the version 28 risk adjustment model.",
            "type": "boolean"
          },
          "is_mcc": {
            "description": "Indicates if this code qualifies as a Major Complication or Comorbidity (MCC).",
            "type": "boolean"
          }
        },
        "required": [
          "code",
          "display",
          "system",
          "is_hcc",
          "is_mcc"
        ]
      },
      "snomed_entry": {
        "type": "object",
        "description": "A SNOMED CT entry.",
        "properties": {
          "system": {
            "type": "string",
            "description": "The used coding system, only SNOMED CT is supported.",
            "enum": [
              "http://snomed.info/sct"
            ]
          },
          "code": {
            "type": "string",
            "example": "38341003",
            "description": "Code of the [SNOMED CT](https://www.snomed.org) concept."
          },
          "display": {
            "type": "string",
            "example": "Hypertensive disorder",
            "description": "Description of the [SNOMED CT](https://www.snomed.org) concept."
          }
        },
        "required": [
          "system",
          "code",
          "display"
        ]
      },
      "note_section_subsection_with_codes": {
        "type": "object",
        "description": "A subsection of a note section, with its normalized codes inlined. In practice only the Assessment & Plan section of A&P-merged templates has subsections.",
        "properties": {
          "title": {
            "type": "string",
            "description": "Short subsection title (typically a clinical problem name). May be `null`  (e.g. subsections appended by dot phrase auto-apply).",
            "example": "Hypertension"
          },
          "text": {
            "type": "string",
            "description": "Free-text content of the subsection.",
            "example": "BP elevated to 160/100. Continue lisinopril."
          },
          "icd10_codes": {
            "type": "array",
            "description": "ICD-10 codes attached to this subsection. Empty when no codes are available (e.g. code extraction disabled, or not completed at export time).",
            "items": {
              "$ref": "#/components/schemas/icd10_entry_with_hcc_mcc"
            }
          },
          "snomed_codes": {
            "type": "array",
            "description": "SNOMED CT codes attached to this subsection. Empty when no codes are available (e.g. code extraction disabled, or not completed at export time).",
            "items": {
              "$ref": "#/components/schemas/snomed_entry"
            }
          }
        },
        "required": [
          "text",
          "icd10_codes",
          "snomed_codes"
        ]
      },
      "note_section_content_subsections": {
        "type": "object",
        "description": "Structured note section content as per-problem subsections.",
        "required": [
          "type",
          "subsections"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "SUBSECTIONS"
            ]
          },
          "subsections": {
            "type": "array",
            "description": "Structured subsections with their normalized codes, in note order. In practice only the Assessment & Plan section of A&P-merged templates is structured this way.",
            "items": {
              "$ref": "#/components/schemas/note_section_subsection_with_codes"
            }
          }
        }
      },
      "note_section_content": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/note_section_content_text",
            "title": "TEXT"
          },
          {
            "$ref": "#/components/schemas/note_section_content_subsections",
            "title": "SUBSECTIONS"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "TEXT": "#/components/schemas/note_section_content_text",
            "SUBSECTIONS": "#/components/schemas/note_section_content_subsections"
          }
        }
      },
      "note_section": {
        "type": "object",
        "description": "A note section.",
        "properties": {
          "category": {
            "$ref": "#/components/schemas/note_section_type"
          },
          "title": {
            "type": "string",
            "description": "The section title.",
            "example": "Chief complaint"
          },
          "content": {
            "type": "string",
            "deprecated": true,
            "description": "Content of the note section, flattened as text. Deprecated: replace your usage with `structured_content`, which carries the same content in a structured form.",
            "example": "Sleep disorder"
          },
          "structured_content": {
            "$ref": "#/components/schemas/note_section_content",
            "description": "Content of the note section, discriminated by `type`. Always present: read `type` to know whether the section carries plain text or structured subsections."
          }
        },
        "required": [
          "content",
          "structured_content"
        ]
      },
      "note": {
        "type": "object",
        "description": "The generated note.",
        "properties": {
          "sections": {
            "type": "array",
            "description": "Content of the note structured in multiple sections.",
            "items": {
              "$ref": "#/components/schemas/note_section"
            }
          },
          "free_text": {
            "type": "string",
            "description": "Free-form text written by the practitioner, alongside the note sections."
          }
        },
        "required": [
          "sections"
        ]
      },
      "speaker": {
        "type": "string",
        "enum": [
          "DOCTOR",
          "PATIENT",
          "UNSPECIFIED"
        ],
        "description": "Who said the text in this transcript item.",
        "example": "DOCTOR"
      },
      "speech_locale": {
        "type": "string",
        "enum": [
          "ENGLISH_US",
          "ENGLISH_UK",
          "SPANISH_ES",
          "SPANISH_MX",
          "FRENCH_FR",
          "ARABIC_EG",
          "ARABIC_LB",
          "ARABIC_MA",
          "ARABIC_SA",
          "ARMENIAN_AM",
          "BENGALI_IN",
          "CANTONESE_CN",
          "CROATIAN_HR",
          "FILIPINO_PH",
          "GERMAN_DE",
          "GREEK_GR",
          "GUJARATI_IN",
          "HEBREW_IL",
          "HINDI_IN",
          "ITALIAN_IT",
          "JAPANESE_JP",
          "KHMER_KH",
          "KOREAN_KR",
          "MANDARIN_CN",
          "PERSIAN_IR",
          "POLISH_PL",
          "PORTUGUESE_PT",
          "PUNJABI_IN",
          "RUSSIAN_RU",
          "SERBIAN_RS",
          "TAMIL_IN",
          "TELUGU_IN",
          "THAI_TH",
          "URDU_IN",
          "VIETNAMESE_VN",
          "HAITIAN_HT"
        ],
        "example": "ENGLISH_US"
      },
      "transcript_item": {
        "type": "object",
        "description": "A portion of the transcribed consultation.",
        "properties": {
          "text": {
            "type": "string",
            "description": "The transcribed text.",
            "example": "Also, I’m allergic to peanuts."
          },
          "speaker_type": {
            "$ref": "#/components/schemas/speaker"
          },
          "locale": {
            "$ref": "#/components/schemas/speech_locale",
            "description": "Locale for this transcript item, detected by the speech-to-text engine from the list of locales in the input."
          },
          "start_offset_ms": {
            "type": "integer",
            "description": "Start time of this transcription item as the offset, in milliseconds, from the start of the audio file.",
            "example": 65100
          },
          "end_offset_ms": {
            "type": "integer",
            "description": "End time of this transcription item as the offset, in milliseconds, from the start of the audio file. Equals the `start_time_ms` plus the duration of the related transcribed audio portion.",
            "example": 69300
          }
        },
        "required": [
          "text",
          "speaker_type",
          "start_offset_ms",
          "end_offset_ms"
        ]
      },
      "transcript": {
        "type": "array",
        "description": "Transcript items from the audio file.",
        "items": {
          "$ref": "#/components/schemas/transcript_item"
        }
      },
      "visit_diagnoses": {
        "type": "array",
        "description": "New visit diagnosis suggestions with ICD-10 codes, corresponding to the \"New Visit Diagnoses Suggestions\" section in the Nabla UI. Only available for US organizations with the ICD-10 feature enabled. Omitted when normalization has not run or the ICD-10 feature is disabled for the org. Only includes visit diagnoses that have not been deleted (i.e., struck-through) in the Nabla UI.\n",
        "items": {
          "$ref": "#/components/schemas/icd10_entry_with_hcc_mcc"
        }
      },
      "external_metadata": {
        "type": "object",
        "description": "Opaque key-value map from your EHR. Nabla stores it encrypted and echoes it unchanged on export callbacks. It is not used for note generation.\nOmitting the field leaves existing metadata unchanged. Send `{}` to clear it.\nYou can specify up to 50 keys, with key names up to 40 characters long. All values must be strings up to 500 characters long.",
        "additionalProperties": {
          "type": "string",
          "maxLength": 500
        },
        "maxProperties": 50
      },
      "note_export_data": {
        "type": "object",
        "properties": {
          "external_patient_id": {
            "type": "string",
            "description": "External patient ID from your app, that you provided at launch"
          },
          "external_encounter_id": {
            "type": "string",
            "description": "External encounter ID from your app, that you provided at launch"
          },
          "external_provider_id": {
            "type": "string",
            "description": "External patient ID from your app, that you provided at launch"
          },
          "note": {
            "$ref": "#/components/schemas/note",
            "description": "The exported note."
          },
          "transcript": {
            "$ref": "#/components/schemas/transcript",
            "description": "The exported note transcript."
          },
          "visit_diagnoses": {
            "$ref": "#/components/schemas/visit_diagnoses"
          },
          "external_metadata": {
            "$ref": "#/components/schemas/external_metadata"
          }
        },
        "required": [
          "external_patient_id",
          "external_encounter_id",
          "external_provider_id",
          "note"
        ]
      },
      "callback_note_export": {
        "x-sensitive-medical-data": true,
        "allOf": [
          {
            "$ref": "#/components/schemas/base_callback"
          },
          {
            "type": "object",
            "description": "Event sent when a note is exported.",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/note_export_data"
              }
            },
            "required": [
              "data"
            ]
          }
        ]
      },
      "patient_instructions": {
        "type": "object",
        "properties": {
          "instructions": {
            "type": "string",
            "description": "List of instructions for the patient.",
            "example": "- Order a sleep test that you can do at home. This will help us understand more about how you sleep.\n- After you've done the sleep test, we'll talk about the results in our next meeting."
          }
        },
        "required": [
          "instructions"
        ]
      },
      "patient_instructions_export_data": {
        "type": "object",
        "properties": {
          "external_patient_id": {
            "type": "string",
            "description": "External patient ID from your app, that you provided at launch"
          },
          "external_encounter_id": {
            "type": "string",
            "description": "External encounter ID from your app, that you provided at launch"
          },
          "external_provider_id": {
            "type": "string",
            "description": "External patient ID from your app, that you provided at launch"
          },
          "patient_instructions": {
            "$ref": "#/components/schemas/patient_instructions",
            "description": "The exported patient_instructions."
          },
          "external_metadata": {
            "$ref": "#/components/schemas/external_metadata"
          }
        },
        "required": [
          "external_patient_id",
          "external_encounter_id",
          "external_provider_id",
          "patient_instructions"
        ]
      },
      "callback_patient_instructions_export": {
        "x-sensitive-medical-data": true,
        "allOf": [
          {
            "$ref": "#/components/schemas/base_callback"
          },
          {
            "type": "object",
            "description": "Event sent when patient instructions are exported.",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/patient_instructions_export_data"
              }
            },
            "required": [
              "data"
            ]
          }
        ]
      },
      "callback": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/callback_note_export",
            "title": "NOTE_EXPORT"
          },
          {
            "$ref": "#/components/schemas/callback_patient_instructions_export",
            "title": "PATIENT_INSTRUCTIONS_EXPORT"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "NOTE_EXPORT": "#/components/schemas/callback_note_export",
            "PATIENT_INSTRUCTIONS_EXPORT": "#/components/schemas/callback_patient_instructions_export"
          }
        },
        "example": {
          "request_uuid": "0cf0b04d-5bbe-47a9-9601-3dd037644f65",
          "type": "NOTE_EXPORT",
          "data": {
            "patient_id": "patient_123456",
            "encounter_id": "encounter_987654",
            "provider_id": "provider_456789",
            "note": {
              "sections": [
                {
                  "type": "CHIEF_COMPLAINT",
                  "title": "Chief complaint",
                  "content": "- Persistent fatigue\n- Mild headaches on the right side"
                },
                {
                  "type": "ASSESSMENT_AND_PLAN",
                  "title": "Past medical history",
                  "content": "- Hypertension\n- Elevated blood sugar levels"
                },
                {
                  "type": "RESULTS",
                  "title": "Lab results",
                  "content": "- Blood sugar level: 1.4 g/L\n- LDL cholesterol: 2 g/L"
                }
              ]
            }
          }
        }
      },
      "callback_response": {
        "type": "object",
        "properties": {
          "request_uuid": {
            "$ref": "#/components/schemas/uuid",
            "description": "The request UUID you provided in the request."
          }
        },
        "required": [
          "request_uuid"
        ]
      }
    }
  }
}