Appointments

The Appointments API manages scheduling for dental practices. Create, update, cancel, and reschedule appointments, check availability, and retrieve appointment history.

The Appointment Object

Field	Type	Description
id	string	Unique appointment ID (apt_*)
patient_id	string	Patient ID (pat_*)
dentist_id	string	Dentist/staff ID (usr_*)
start_time	string	ISO 8601 datetime (UTC)
end_time	string	ISO 8601 datetime (UTC)
type	enum	consultation, cleaning, filling, extraction, root_canal, implant, follow_up, other
status	enum	scheduled, confirmed, in_progress, completed, cancelled, no_show
notes	string	Internal notes for the appointment
location_id	string	Clinic/location ID (loc_*)
created_at	string	ISO 8601 timestamp (UTC)

GET/appointments

List all appointments

Returns a paginated list of appointments. Filter by date range, patient, dentist, or status.

Parameters

Parameter	Type	Required	Description
patient_id	string	Optional	Filter by patient ID
dentist_id	string	Optional	Filter by dentist ID
status	string	Optional	Filter by status: scheduled, confirmed, completed, cancelled
start_date	string	Optional	Filter appointments starting on or after this date (ISO 8601)
end_date	string	Optional	Filter appointments starting on or before this date (ISO 8601)
limit	integer	Optional	Results per page (1-100). Default: 20
cursor	string	Optional	Pagination cursor

Example Request

Requestbash

curl -X GET "https://api.odento.app/api/v1/appointments?start_date=2025-01-15T00:00:00Z&end_date=2025-01-22T23:59:59Z&status=scheduled" \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "apt_7a3b9c1d2e5f8a4b",
        "patient_id": "pat_5f8d3a2b1c9e4a7b",
        "dentist_id": "usr_abc123",
        "start_time": "2025-01-22T10:00:00Z",
        "end_time": "2025-01-22T11:00:00Z",
        "type": "consultation",
        "status": "scheduled",
        "notes": "Routine checkup",
        "location_id": "loc_xyz789",
        "created_at": "2025-01-15T08:00:00Z"
      }
    ],
    "pagination": {
      "has_more": false,
      "next_cursor": null,
      "per_page": 20
    }
  }
}

Try It Out

API Playground— try it out

https://api.odento.app

Headers

This is a simulated response — no real API calls are made from the browser.

POST/appointments

Create an appointment

Creates a new appointment. The API checks for scheduling conflicts and returns a 409 if the time slot is already booked.

Parameters

Parameter	Type	Required	Description
patient_id	string	Required	Patient ID (pat_*)
dentist_id	string	Required	Dentist ID (usr_*)
start_time	string	Required	ISO 8601 datetime (UTC)
end_time	string	Required	ISO 8601 datetime (UTC)
type	string	Required	Appointment type (consultation, cleaning, filling, etc.)
location_id	string	Required	Clinic/location ID (loc_*)
notes	string	Optional	Internal notes

Example Request

Requestbash

curl -X POST https://api.odento.app/api/v1/appointments \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "pat_5f8d3a2b1c9e4a7b",
    "dentist_id": "usr_abc123",
    "start_time": "2025-01-22T10:00:00Z",
    "end_time": "2025-01-22T11:00:00Z",
    "type": "consultation",
    "location_id": "loc_xyz789",
    "notes": "Routine checkup"
  }'

Example Response

Response201json

{
  "success": true,
  "data": {
    "id": "apt_7a3b9c1d2e5f8a4b",
    "patient_id": "pat_5f8d3a2b1c9e4a7b",
    "dentist_id": "usr_abc123",
    "start_time": "2025-01-22T10:00:00Z",
    "end_time": "2025-01-22T11:00:00Z",
    "type": "consultation",
    "status": "scheduled",
    "notes": "Routine checkup",
    "location_id": "loc_xyz789",
    "created_at": "2025-01-15T08:00:00Z"
  }
}

GET/appointments/{id}

Retrieve an appointment

Retrieves a single appointment by ID, including patient and dentist summary.

Parameters

Parameter	Type	Required	Description
id	string	Required	The appointment ID (apt_*)

Example Request

Requestbash

curl -X GET https://api.odento.app/api/v1/appointments/apt_7a3b9c1d2e5f8a4b \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "id": "apt_7a3b9c1d2e5f8a4b",
    "patient_id": "pat_5f8d3a2b1c9e4a7b",
    "patient": {
      "first_name": "Priya",
      "last_name": "Sharma",
      "phone": "+919876543210"
    },
    "dentist_id": "usr_abc123",
    "dentist": {
      "name": "Dr. Priya Sharma",
      "specialization": "General Dentistry"
    },
    "start_time": "2025-01-22T10:00:00Z",
    "end_time": "2025-01-22T11:00:00Z",
    "type": "consultation",
    "status": "scheduled",
    "notes": "Routine checkup",
    "location_id": "loc_xyz789",
    "created_at": "2025-01-15T08:00:00Z"
  }
}

PATCH/appointments/{id}

Update an appointment

Updates an appointment's fields. Use this to change the type, notes, or status (e.g., mark as completed). To change the time, use the reschedule endpoint.

Parameters

Parameter	Type	Required	Description
id	string	Required	The appointment ID (apt_*)
type	string	Optional	Updated appointment type
status	string	Optional	Updated status: confirmed, in_progress, completed, no_show
notes	string	Optional	Updated notes

Example Request

Requestbash

curl -X PATCH https://api.odento.app/api/v1/appointments/apt_7a3b9c1d2e5f8a4b \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "notes": "Patient showed mild gingivitis. Recommended scaling."
  }'

Example Response

Response200json

{
  "success": true,
  "data": {
    "id": "apt_7a3b9c1d2e5f8a4b",
    "patient_id": "pat_5f8d3a2b1c9e4a7b",
    "dentist_id": "usr_abc123",
    "start_time": "2025-01-22T10:00:00Z",
    "end_time": "2025-01-22T11:00:00Z",
    "type": "consultation",
    "status": "completed",
    "notes": "Patient showed mild gingivitis. Recommended scaling.",
    "location_id": "loc_xyz789",
    "created_at": "2025-01-15T08:00:00Z"
  }
}

POST/appointments/{id}/reschedule

Reschedule an appointment

Changes the start and end time of an appointment. The API checks for conflicts and returns 409 if the new slot is unavailable. The appointment status is reset to 'scheduled'.

Parameters

Parameter	Type	Required	Description
id	string	Required	The appointment ID (apt_*)
start_time	string	Required	New start time (ISO 8601 UTC)
end_time	string	Required	New end time (ISO 8601 UTC)
reason	string	Optional	Reason for rescheduling (logged for audit)

Example Request

Requestbash

curl -X POST https://api.odento.app/api/v1/appointments/apt_7a3b9c1d2e5f8a4b/reschedule \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2025-01-25T14:00:00Z",
    "end_time": "2025-01-25T15:00:00Z",
    "reason": "Patient requested later time"
  }'

Example Response

Response200json

{
  "success": true,
  "data": {
    "id": "apt_7a3b9c1d2e5f8a4b",
    "patient_id": "pat_5f8d3a2b1c9e4a7b",
    "dentist_id": "usr_abc123",
    "start_time": "2025-01-25T14:00:00Z",
    "end_time": "2025-01-25T15:00:00Z",
    "type": "consultation",
    "status": "scheduled",
    "notes": "Routine checkup",
    "location_id": "loc_xyz789",
    "created_at": "2025-01-15T08:00:00Z"
  }
}

POST/appointments/{id}/cancel

Cancel an appointment

Cancels an appointment. A cancellation reason is required and logged for audit. Cancelled appointments cannot be reactivated — create a new one instead.

Parameters

Parameter	Type	Required	Description
id	string	Required	The appointment ID (apt_*)
reason	string	Required	Cancellation reason

Example Request

Requestbash

curl -X POST https://api.odento.app/api/v1/appointments/apt_7a3b9c1d2e5f8a4b/cancel \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Patient unavailable on new date"
  }'

Example Response

Response200json

{
  "success": true,
  "data": {
    "id": "apt_7a3b9c1d2e5f8a4b",
    "status": "cancelled",
    "cancelled_at": "2025-01-16T09:30:00Z",
    "cancellation_reason": "Patient unavailable on new date"
  }
}

GET/appointments/availability

Check availability

Returns available time slots for a given dentist, location, and date range. Use this before creating an appointment to find open slots.

Parameters

Parameter	Type	Required	Description
dentist_id	string	Required	Dentist ID (usr_*)
location_id	string	Required	Location ID (loc_*)
date	string	Required	Date to check (YYYY-MM-DD)
duration_minutes	integer	Optional	Required slot duration. Default: 30

Example Request

Requestbash

curl -X GET "https://api.odento.app/api/v1/appointments/availability?dentist_id=usr_abc123&location_id=loc_xyz789&date=2025-01-22&duration_minutes=60" \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "date": "2025-01-22",
    "dentist_id": "usr_abc123",
    "slots": [
      { "start_time": "2025-01-22T09:00:00Z", "end_time": "2025-01-22T10:00:00Z", "available": true },
      { "start_time": "2025-01-22T10:00:00Z", "end_time": "2025-01-22T11:00:00Z", "available": false },
      { "start_time": "2025-01-22T11:00:00Z", "end_time": "2025-01-22T12:00:00Z", "available": true },
      { "start_time": "2025-01-22T14:00:00Z", "end_time": "2025-01-22T15:00:00Z", "available": true }
    ]
  }
}

The Appointment Object

List all appointments

Parameters

Example Request

Example Response

Try It Out

Create an appointment

Parameters

Example Request

Example Response

Retrieve an appointment

Parameters

Example Request

Example Response

Update an appointment

Parameters

Example Request

Example Response

Reschedule an appointment

Parameters

Example Request

Example Response

Cancel an appointment

Parameters

Example Request

Example Response

Check availability

Parameters

Example Request

Example Response

Was this page helpful?