{ "openapi": "3.0.3", "info": { "title": "Nabla Connect Server API", "description": "Reference for the server-side Nabla Connect API.", "version": "1.0.0" }, "security": [ { "bearer": [] } ], "paths": { "/oauth/token": { "post": { "summary": "Authenticate your backend", "description": "Use this endpoint to get a medium-lived JWT access token for your backend to perform calls the Server API exposed by Nabla. See the [Authentication](/connect/guides/authentication) guide for details on how to construct the client assertion.", "tags": [ "Authentication" ], "operationId": "oauth-generate-server-access-token", "x-unauthenticated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "This endpoint only supports the 'client_credentials' value.", "example": "client_credentials" }, "client_assertion_type": { "type": "string", "description": "This endpoint only supports the 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' value.", "example": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" }, "client_assertion": { "type": "string", "description": "A short-lived JWT assertion that serves to authenticate this request." } }, "required": [ "grant_type", "client_assertion_type", "client_assertion" ] } } } }, "responses": { "200": { "description": "A JWT access token that can be used to access the server API.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "$ref": "#/components/schemas/jwt_token" }, "expires_in": { "type": "integer", "description": "The lifetime of the access token, in seconds." } }, "required": [ "access_token", "expires_in" ] } } } } } } }, "/users": { "post": { "summary": "Create or update a provider user", "description": "Upserts a provider user. Matching is done using external_provider_id. If a matching user exists, updates their settings. Otherwise, provisions a new user. Returns 409 if external_provider_id and provider_email identify different existing users.", "tags": [ "User" ], "operationId": "provision-users", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provision_user_request" } } } }, "responses": { "200": { "description": "The upserted user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provision_user_response" } } } } } } }, "/users/by_external_id/{external_provider_id}": { "parameters": [ { "name": "external_provider_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The external provider ID of the user." } ], "delete": { "summary": "Delete a user", "description": "Permanently deletes a user and all their data. This action is irreversible. If the user does not exist, returns 404.", "tags": [ "User" ], "operationId": "delete-user-by-external-id", "responses": { "204": { "description": "User successfully deleted." } } } }, "/users/by_external_id/{external_provider_id}/deactivate": { "parameters": [ { "name": "external_provider_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The external provider ID of the user." } ], "post": { "summary": "Deactivate a user", "description": "Deactivates a user. Deactivated users cannot access the Nabla app. Use POST .../activate to reactivate a deactivated user. If the user does not exist, returns 404. If the user is already deactivated, returns 204.", "tags": [ "User" ], "operationId": "deactivate-user-by-external-id", "responses": { "204": { "description": "User successfully deactivated." } } } }, "/users/by_external_id/{external_provider_id}/activate": { "parameters": [ { "name": "external_provider_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The external provider ID of the user." } ], "post": { "summary": "Activate a user", "description": "Activates (or reactivates) a user, granting them access to the Nabla app. If the user does not exist, returns 404. If the user is already active, returns 204.", "tags": [ "User" ], "operationId": "activate-user-by-external-id", "responses": { "204": { "description": "User successfully activated." } } } }, "/encounters": { "post": { "x-multi-wired-handler": true, "summary": "Create or update an encounter", "description": "Create or update an encounter with the provided details and returns an url to access Nabla. Navigating to this URL will log in the provider into Nabla automatically, and open the app on this encounter.", "tags": [ "Encounter" ], "operationId": "create-or-update-encounters", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_or_update_encounter_request" } } } }, "responses": { "200": { "description": "The encounter URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/encounter_url_response" } } } } } } }, "/encounters/url": { "post": { "x-multi-wired-handler": true, "summary": "Generate encounter URL", "description": "Generate a URL to access an existing Nabla encounter. Navigating to this url will log in the provider into Nabla automatically, and open the app on this encounter.", "tags": [ "Encounter" ], "operationId": "generate-encounters-url", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generate_encounter_url_request" } } } }, "responses": { "200": { "description": "The encounter URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/encounter_url_response" } } } } } } } }, "components": { "schemas": { "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" } ] } } } }, "note_export": { "$ref": "#/components/schemas/callback_note_export" }, "patient_instructions_export": { "$ref": "#/components/schemas/callback_patient_instructions_export" }, "jwt_token": { "type": "string", "description": "An authentication token using the JWT serialization format. JWT tokens contain varying data (depending on their intended use) and use a signature to guarantee their authenticity.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwic3ViIjoiMTIzNDU2Nzg5MCIsIm5hbWUiOiJKb2huIERvZSIsImlhdCI6MTUxNjIzOTAyMn0.v5qdy8w9Ygs5fdic9a1LuX76PUdx3omYd5GlDTAF3Ug" }, "specialty_kind": { "type": "string", "description": "Specialty kind.", "enum": [ "ADDICTION_MEDICINE", "PAIN_MEDICINE", "ALLERGY_AND_IMMUNOLOGY", "ANESTHESIOLOGY", "ONCOLOGY", "CARDIOLOGY", "SURGERY", "DERMATOLOGY", "DIABETOLOGY", "ENDOCRINOLOGY", "GENETICS", "GERIATRICS", "GYNECOLOGY", "HEMATOLOGY", "HEPATOLOGY", "GASTROENTEROLOGY", "SPORTS_MEDICINE", "OCCUPATIONAL_MEDICINE", "GENERAL_MEDICINE", "FORENSIC_MEDICINE", "PHYSICAL_MEDICINE_AND_REHABILITATION", "NEPHROLOGY", "NEUROLOGY", "NUTRITION", "DIETETICS", "OPHTHALMOLOGY", "ENT", "PEDIATRICS", "PULMONOLOGY", "PSYCHIATRY", "RHEUMATOLOGY", "RADIOLOGY", "IMMUNOLOGY", "INFECTIOUS_DISEASE", "SEXUAL_MEDICINE", "TOXICOLOGY", "UROLOGY", "MIDWIFE", "EMERGENCY_MEDICINE", "NURSE", "PSYCHOLOGY", "PSYCHOTHERAPY", "INTERNAL_MEDICINE", "FAMILY_MEDICINE", "DENTIST", "VETERINARIAN", "PHYSIOTHERAPY", "CHIROPRACTIC", "OSTEOPATHIC_MEDICINE", "ORTHOPEDICS", "OTHER", "LACTATION_CONSULTANT", "PODIATRY", "GENERAL_PRACTICE", "HOSPITAL_MEDICINE", "BEHAVIORAL_HEALTH", "MENTAL_HEALTH", "SUBSTANCE_USE_DISORDER", "VASCULAR_MEDICINE", "LIFESTYLE_MEDICINE", "PREVENTIVE_MEDICINE", "PUBLIC_HEALTH", "ADOLESCENT_MEDICINE", "WOUND_CARE", "NEUROSURGERY", "PLASTIC_SURGERY", "PALLIATIVE_CARE", "TRANSPLANT_MEDICINE", "OBESITY_MEDICINE", "CASE_MANAGEMENT", "CARE_MANAGEMENT", "CARE_COORDINATION", "SOCIAL_WORK", "PATHOLOGY", "RADIATION_ONCOLOGY", "SLEEP_MEDICINE", "AUDIOLOGY", "REPRODUCTIVE_ENDOCRINOLOGY", "PHARMACIST", "OCCUPATIONAL_THERAPY", "SPEECH_LANGUAGE_PATHOLOGY" ], "example": "GENERAL_PRACTICE" }, "provision_user_specialty_request": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/specialty_kind" }, "other_specialty_name": { "type": "string", "nullable": true, "description": "Required when kind is OTHER." } }, "required": [ "kind" ] }, "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" }, "provision_user_settings_request": { "type": "object", "properties": { "specialty": { "$ref": "#/components/schemas/provision_user_specialty_request" }, "speech_locale": { "$ref": "#/components/schemas/speech_locale" }, "secondary_speech_locale": { "$ref": "#/components/schemas/speech_locale" } }, "required": [ "specialty", "speech_locale" ] }, "provision_user_request": { "type": "object", "description": "Input required to upsert a Nabla Connect user.", "properties": { "provider_email": { "type": "string", "description": "Provider email address. Primary identity key.", "minLength": 1 }, "external_provider_id": { "type": "string", "description": "External provider ID from EHR.", "minLength": 1, "maxLength": 256 }, "settings": { "$ref": "#/components/schemas/provision_user_settings_request" } }, "required": [ "provider_email", "external_provider_id" ] }, "provision_user_specialty_response": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/specialty_kind" }, "other_specialty_name": { "type": "string", "nullable": true } }, "required": [ "kind" ] }, "provision_user_settings_response": { "type": "object", "properties": { "specialty": { "$ref": "#/components/schemas/provision_user_specialty_response" }, "speech_locale": { "$ref": "#/components/schemas/speech_locale", "nullable": true }, "secondary_speech_locale": { "$ref": "#/components/schemas/speech_locale", "nullable": true } }, "required": [ "specialty" ] }, "provision_user_response": { "type": "object", "properties": { "provider_email": { "type": "string" }, "external_provider_id": { "type": "string" }, "settings": { "$ref": "#/components/schemas/provision_user_settings_response" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "provider_email", "external_provider_id", "settings", "created_at" ] }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE", "OTHER", "UNKNOWN" ], "description": "The patient's gender." }, "pronouns": { "type": "string", "enum": [ "HE_HIM", "SHE_HER", "THEY_THEM" ], "description": "The patient's pronouns." }, "patient_demographics": { "type": "object", "description": "Demographic details about the patient.", "properties": { "name": { "type": "string", "description": "The patient's name." }, "birth_date": { "type": "string", "format": "date", "description": "The patient's birthdate (YYYY-MM-DD format).", "example": "1996-03-21" }, "gender": { "$ref": "#/components/schemas/gender" }, "pronouns": { "$ref": "#/components/schemas/pronouns" } }, "required": [ "name", "birth_date", "gender" ] }, "icd10_entry_request": { "type": "object", "description": "An ICD-10-CM coding entry supplied in Connect structured context.", "properties": { "system": { "type": "string", "description": "The coding system URI. Only ICD-10-CM is accepted when persisting visit diagnoses.", "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." } }, "required": [ "system", "code", "display" ] }, "structured_context_request": { "type": "object", "description": "Structured context about the patient and the encounter, which will be taken into account when generating the note.", "properties": { "patient_demographics": { "$ref": "#/components/schemas/patient_demographics" }, "visit_diagnoses": { "type": "array", "description": "Optional encounter visit diagnoses as ICD-10-CM codings (system, code, display) from the integrating EHR. If some of these diagnoses apply to the current note, they are prioritized when producing visit diagnosis coding in note generation outputs. When this property is sent on create or update, its contents replace persisted encounter visit diagnoses; send an empty array to clear them. When omitted, existing persisted diagnoses are left unchanged.\n", "items": { "$ref": "#/components/schemas/icd10_entry_request" } } }, "required": [ "patient_demographics" ] }, "create_or_update_encounter_request": { "type": "object", "description": "Input data required to create a new encounter, IDs should be the ones from your EHR system.", "properties": { "provider_email": { "type": "string" }, "external_patient_id": { "type": "string" }, "external_encounter_id": { "type": "string" }, "external_provider_id": { "type": "string" }, "target_origin": { "type": "string" }, "unstructured_context": { "type": "string", "description": "Some unstructured contextual information that will be used to generate the note (for example name, gender, age, pronouns, medical history). Generating the encounter note will take longer if you pass a long `unstructured_context`.", "maxLength": 10000 }, "structured_context": { "$ref": "#/components/schemas/structured_context_request" } }, "required": [ "provider_email", "external_patient_id", "external_encounter_id", "external_provider_id", "structured_context" ] }, "encounter_url_response": { "type": "object", "description": "The encounter URL response.", "properties": { "encounter_url": { "type": "string", "description": "URL to open the created encounter." } } }, "generate_encounter_url_request": { "type": "object", "description": "Input data required to generate an encounter URL, IDs should be the ones from your EHR system.", "properties": { "external_encounter_id": { "type": "string" }, "external_provider_id": { "type": "string" } }, "required": [ "external_encounter_id", "external_provider_id" ] }, "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": { "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" } }, "required": [ "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" }, "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" } }, "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" ] }, "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" } }, "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" } }, "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." } }, "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" ] } ] } } }, "x-squad": "api" }