Dental Examination API Documentation

Overview

The Dental Examination API provides endpoints for managing comprehensive dental examination records with flexible data structures, dental notation system, and event integration capabilities.

Base URL

{{url}}/parts/patients/:patient_id/dental_examinations

Endpoints

1. List Dental Examinations

Method: GET
URL: /parts/patients/:patient_id/dental_examinations
Purpose: Retrieve dental examinations for a specific patient

Query Parameters

Parameter	Type	Description
`date_from`	string	Filter by examination date (YYYY-MM-DD)
`date_to`	string	Filter by examination date (YYYY-MM-DD)
`search`	string	Search in notes and examination data
`sort_by`	string	Sort field: `examination_date`, `created_at`
`sort_order`	string	Sort order: `asc`, `desc`
`page`	integer	Page number
`perpage`	integer	Records per page

Response

{
  "success": true,
  "message": "Dental examinations retrieved successfully",
  "data": {
    "dental_examinations": [
      {
        "id": 123,
        "clinic_patient_id": 456,
        "doctor_id": 789,
        "event_id": 101,
        "event_type": "appointment",
        "examination_date": "2025-01-15",
        "notes": "Routine checkup completed",
        "examination_data": {},
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T10:30:00Z",
        "doctor": {
          "id": 789,
          "name": "Dr. Smith"
        },
        "dental_examination_records": [
          {
            "id": 234,
            "default_dental_notation_id": 11,
            "notes": "Upper right incisor sensitivity",
            "record_data": {},
            "default_dental_notation": {
              "id": 11,
              "tooth_name": "Upper Right Central Incisor",
              "tooth_class": "Incisor",
              "description": "Front tooth, upper right"
            }
          }
        ]
      }
    ],
    "total_pages": 5,
    "total_records": 48
  }
}

2. Get Single Dental Examination

Method: GET
URL: /parts/patients/:patient_id/dental_examinations/:id
Purpose: Retrieve detailed information about a specific dental examination

Response

{
  "success": true,
  "message": "Dental examination fetched successfully",
  "data": {
    "id": 3,
    "clinic_patient_id": 32,
    "doctor_id": 1,
    "event_type": "APPOINTMENT",
    "event_id": 102,
    "examination_date": "2024-11-17",
    "notes": "Patient complains of tooth sensitivity in upper jaws",
    "created_at": "2025-11-17T11:00:48.138Z",
    "updated_at": "2025-11-17T11:06:03.029Z",
    "doctor": {
      "id": 1
    },
    "dental_examination_records": [
      {
        "id": 8,
        "default_dental_notation_id": 1,
        "notes": "Decay detected in occlusal surface",
        "record_data": {
          "severity": "moderate",
          "condition": "moderate_decay",
          "treatment": "restoration_needed"
        },
        "patient_photos_with_details": [
          {
            "id": 6,
            "created_at": "2025-11-17T11:16:50.879Z",
            "photo_records": [
              {
                "id": 9,
                "notes": "Hello",
                "document": {
                  "id": 43,
                  "owner_type": "Clinic",
                  "owner_id": "3",
                  "file_type": "image/png",
                  "original_filename": "512042147-9036d058-07ba-40c6-b7ab-f05079e1f3a0.png",
                  "basic_language_id": 1,
                  "format_type": "KULCARE",
                  "filename": "efcd10f6-9248-4d2d-b2a3-b82ed2776391.png",
                  "urls": {
                    "original": "https://api-stg.kulcare.com/documents/efcd10f6-9248-4d2d-b2a3-b82ed2776391.png",
                    "large": "https://api-stg.kulcare.com/documents/large_efcd10f6-9248-4d2d-b2a3-b82ed2776391.png",
                    "medium": "https://api-stg.kulcare.com/documents/medium_efcd10f6-9248-4d2d-b2a3-b82ed2776391.png",
                    "thumb": "https://api-stg.kulcare.com/documents/thumb_efcd10f6-9248-4d2d-b2a3-b82ed2776391.png"
                  },
                  "language": {
                    "id": 1,
                    "name": "English",
                    "default_name": "en"
                  }
                }
              },
              {
                "id": 10,
                "notes": "abcd",
                "document": {
                  "id": 44,
                  "owner_type": "Clinic",
                  "owner_id": "3",
                  "file_type": "image/jpeg",
                  "original_filename": "34-1.jpg",
                  "basic_language_id": 1,
                  "format_type": "KULCARE",
                  "filename": "06ac2ea0-e3ed-4a78-89a7-5ea1921a08da.jpg",
                  "urls": {
                    "original": "https://api-stg.kulcare.com/documents/06ac2ea0-e3ed-4a78-89a7-5ea1921a08da.jpg",
                    "large": "https://api-stg.kulcare.com/documents/large_06ac2ea0-e3ed-4a78-89a7-5ea1921a08da.jpg",
                    "medium": "https://api-stg.kulcare.com/documents/medium_06ac2ea0-e3ed-4a78-89a7-5ea1921a08da.jpg",
                    "thumb": "https://api-stg.kulcare.com/documents/thumb_06ac2ea0-e3ed-4a78-89a7-5ea1921a08da.jpg"
                  },
                  "language": {
                    "id": 1,
                    "name": "English",
                    "default_name": "en"
                  }
                }
              }
            ]
          }
        ],
        "default_dental_notation": {
          "id": 1,
          "tooth_name": "A",
          "tooth_class": "PRIMARY",
          "description": "Primary central incisor"
        }
      }
    ],
    "examination_data": {
      "treatment_plan": "Apply fluoride varnish",
      "chief_complaint": "Tooth sensitivity",
      "clinical_findings": "Enamel erosion on teeth 16, 26"
    }
  }
}

3. Create Dental Examination

Method: POST
URL: /parts/patients/:patient_id/dental_examinations
Purpose: Create a new dental examination record

Request Body

{
  "dental_examination": {
    "doctor_id": 1,
    "event_id": 102,
    "event_type": "APPOINTMENT",
    "examination_date": "2024-11-17",
    "notes": "Patient complains of tooth sensitivity in upper jaw",
    "examination_data": {
      "chief_complaint": "Tooth sensitivity",
      "clinical_findings": "Enamel erosion on teeth 16, 26",
      "treatment_plan": "Apply fluoride varnish"
    },
    "dental_examination_records": [
      {
        "default_dental_notation_id": 1,
        "notes": "Decay detected in occlusal surface",
        "record_data": {
          "condition": "moderate_decay",
          "treatment": "restoration_needed",
          "severity": "moderate"
        }
      },
      {
        "default_dental_notation_id": 2,
        "notes": "Normal healthy tooth",
        "record_data": {
          "condition": "healthy",
          "treatment": "none_required",
          "severity": "none"
        }
      }
    ]
  }
}

Parameters

Parameter	Type	Required	Description
`doctor_id`	integer	false	Doctor who performed examination
`examination_date`	string	false	Examination date (YYYY-MM-DD)
`notes`	string	false	Examination notes
`examination_data`	object	false	JSON field for flexible data
`event_id`	integer	false	Associated event ID
`event_type`	string	false	Event type: 'appointment', 'prescription'
`dental_examination_records`	array	false	Array of examination records

Dental Examination Record Parameters

Parameter	Type	Required	Description
`default_dental_notation_id`	integer	true	Dental notation system reference
`notes`	string	false	Record-specific notes
`record_data`	object	false	JSON field for custom record data

Response

{
  "success": true,
  "message": "Dental examination created successfully",
  "type": "create",
  "data": {
    "id": 124,
    "clinic_patient_id": 456,
    "doctor_id": 789,
    "examination_date": "2025-01-15",
    "notes": "Initial examination",
    "examination_data": {},
    "created_at": "2025-01-15T14:30:00Z",
    "updated_at": "2025-01-15T14:30:00Z",
    "doctor": {
      "id": 789,
      "name": "Dr. Smith"
    },
    "dental_examination_records": []
  }
}

4. Update Dental Examination

Method: PUT
URL: /parts/patients/:patient_id/dental_examinations/:id
Purpose: Update an existing dental examination

Request Body

Same structure as Create request. For updating records, include the id field in each dental_examination_records object:

{
  "dental_examination": {
    "examination_date": "2024-11-17",
    "notes": "Patient complains of tooth sensitivity in upper jaws",
    "examination_data": {
      "chief_complaint": "Tooth sensitivity",
      "clinical_findings": "Enamel erosion on teeth 16, 26",
      "treatment_plan": "Apply fluoride varnish"
    },
    "dental_examination_records": [
      {
        "id": 8,
        "default_dental_notation_id": 1,
        "notes": "Decay detected in occlusal surface",
        "record_data": {
          "condition": "moderate_decay",
          "treatment": "restoration_needed",
          "severity": "moderate"
        }
      }
    ]
  }
}

5. Delete Dental Examination

Method: DELETE
URL: /parts/patients/:patient_id/dental_examinations/:id
Purpose: Soft-delete a dental examination

Response

{
  "success": true,
  "message": "Dental examination deleted successfully"
}

Authentication

All endpoints require valid authentication token in the Authorization header:

Authorization: Bearer {{auth_token}}
Content-Type: application/json

Authorization Requirements

User must have ENABLE_DENTAL_MODULE feature flag enabled. This is the LEGACY flag store (parts/core FeatureFlag, the basic_feature_flags / feature_flags tables) that this parts/patient controller reads. It is not the system.feature_flags key retired in #2505, which gated the domains encounter workflow.
User must have access to the specified patient
Write operations require appropriate doctor permissions
Patient ID in URL must be accessible to the authenticated user

Data Models

Dental Examination

id: Integer - Primary key
clinic_patient_id: Integer - Associated patient
doctor_id: Integer - Performing doctor
event_id: Integer - Associated event (optional)
event_type: String - Event type (appointment/prescription)
examination_date: Date - Examination date
notes: Text - Examination notes
examination_data: JSON - Flexible examination data
created_at: DateTime - Creation timestamp
updated_at: DateTime - Last update timestamp

Dental Examination Record

id: Integer - Primary key
dental_examination_id: Integer - Parent examination
default_dental_notation_id: Integer - Dental notation reference
notes: Text - Record notes
record_data: JSON - Flexible record data

Dental Notation System

The system uses a dental notation system for tooth identification. Common categories include:

Incisors: Front teeth
Canines: Pointed teeth
Premolars: Bicuspids
Molars: Grinding teeth

Each notation includes tooth name, class, and descriptive information for standardized dental recording.

Event Integration

Dental examinations can be linked to:

Appointments: event_type: "appointment"
Prescriptions: event_type: "prescription"

The system automatically creates reverse associations when events are specified.

Search and Filtering

Available Search Fields

Notes text content
Examination_data JSON content
Doctor name (through association)

Available Filter Fields

date_from/date_to: Examination date range
sort_by: examination_date, created_at
sort_order: asc, desc

Soft Delete

Deletion operations perform soft delete by setting the deleted flag to true. Records remain in the database for audit purposes but are not returned in API responses.

Error Responses

{
  "success": false,
  "errors": [
    {
      "field": "clinic_patient",
      "title": "not found",
      "message": "Patient not found"
    }
  ]
}

Common error types:

clinic_patient.not_found: Patient not found
doctor.not_found: Doctor not found
dental_examination.not_found: Examination not found
user.dental module access not enabled: Feature access denied
validation_error: Invalid input data

Dental Examination API Documentation

OverviewCopy Anchor Link

Base URLCopy Anchor Link

EndpointsCopy Anchor Link

1. List Dental ExaminationsCopy Anchor Link

Query ParametersCopy Anchor Link

ResponseCopy Anchor Link

2. Get Single Dental ExaminationCopy Anchor Link

ResponseCopy Anchor Link

3. Create Dental ExaminationCopy Anchor Link

Request BodyCopy Anchor Link

ParametersCopy Anchor Link

Dental Examination Record ParametersCopy Anchor Link

ResponseCopy Anchor Link

4. Update Dental ExaminationCopy Anchor Link

Request BodyCopy Anchor Link

5. Delete Dental ExaminationCopy Anchor Link

ResponseCopy Anchor Link

AuthenticationCopy Anchor Link

Authorization RequirementsCopy Anchor Link

Data ModelsCopy Anchor Link

Dental ExaminationCopy Anchor Link

Dental Examination RecordCopy Anchor Link

Dental Notation SystemCopy Anchor Link

Event IntegrationCopy Anchor Link

Search and FilteringCopy Anchor Link

Available Search FieldsCopy Anchor Link

Available Filter FieldsCopy Anchor Link

Soft DeleteCopy Anchor Link

Error ResponsesCopy Anchor Link

On this page

Overview

Base URL

Endpoints

1. List Dental Examinations

Query Parameters

Response

2. Get Single Dental Examination

Response

3. Create Dental Examination

Request Body

Parameters

Dental Examination Record Parameters

Response

4. Update Dental Examination

Request Body

5. Delete Dental Examination

Response

Authentication

Authorization Requirements

Data Models

Dental Examination

Dental Examination Record

Dental Notation System

Event Integration

Search and Filtering

Available Search Fields

Available Filter Fields

Soft Delete

Error Responses