Get All Appointments

Overview

This endpoint returns all appointments in the system with powerful filtering options, plus additional statistics about today’s appointments. It automatically updates expired pending appointments to “Ausente” (no-show) status before returning results.

This endpoint automatically runs a background process to mark pending appointments as “Ausente” if their date/time has passed.

Authentication

Requires a valid JWT token in the request headers.

Authorization: Bearer <jwt_token>

Query Parameters

string

Search appointments by patient DNI. Performs a partial match using SQL LIKE.Example: search=12345678

professionalID

number

Filter appointments by professional ID. Only returns appointments for the specified professional.Example: professionalID=5

state

string

Filter appointments by state. Must be one of the valid appointment states.Valid values:

Pendiente - Pending appointment
Atendido - Completed appointment
Cancelado - Cancelled appointment
Ausente - No-show (patient didn’t attend)

Example: state=Pendiente

Response

Returns a comprehensive object with multiple appointment datasets:

appointments

array

Array of all appointments matching the filter criteria, ordered by date (most recent first). Each appointment includes:

Show Appointment Object

number

Unique appointment identifier

patientID

number

Patient’s ID

professionalID

number

Professional’s ID

date

string

Appointment date in ISO 8601 format (YYYY-MM-DD)

time

string

Appointment time in 24-hour format (HH:mm:ss)

description

string

Reason for the appointment or notes

state

string

Current appointment state (Pendiente, Atendido, Cancelado, Ausente)

Patient

object

Patient information

name: Patient’s first name
surname: Patient’s last name
dni: Patient’s DNI number

Professional

object

Professional information

name: Professional’s first name
surname: Professional’s last name
dni: Professional’s DNI number
Speciality: Object with speciality name

appointmentsOfToday

array

Array of appointments scheduled for today only, ordered by time (earliest first). Uses the same structure as appointments array but without speciality information.

countAppointments

number

Total count of appointments scheduled for today (all states)

countCancelled

number

Count of cancelled appointments for today only

Examples

curl -X GET "https://api.clinicavitalis.com/appointments" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Filter by Professional

curl -X GET "https://api.clinicavitalis.com/appointments?professionalID=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Search by Patient DNI and Filter by State

curl -X GET "https://api.clinicavitalis.com/appointments?search=12345678&state=Pendiente" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response Example

{
  "appointments": [
    {
      "id": 123,
      "patientID": 45,
      "professionalID": 12,
      "date": "2026-03-15",
      "time": "10:30:00",
      "description": "Control mensual de diabetes",
      "state": "Pendiente",
      "Patient": {
        "name": "María",
        "surname": "González",
        "dni": 12345678
      },
      "Professional": {
        "name": "Dr. Carlos",
        "surname": "Fernández",
        "dni": 98765432,
        "Speciality": {
          "name": "Endocrinología"
        }
      }
    }
  ],
  "appointmentsOfToday": [
    {
      "id": 124,
      "patientID": 46,
      "professionalID": 13,
      "date": "2026-03-11",
      "time": "09:00:00",
      "description": "Consulta general",
      "state": "Pendiente",
      "Patient": {
        "name": "Juan",
        "surname": "Pérez",
        "dni": 87654321
      },
      "Professional": {
        "name": "Dra. Ana",
        "surname": "Martínez",
        "dni": 45678901
      }
    }
  ],
  "countAppointments": 8,
  "countCancelled": 1
}

Error Responses

404 Not Found

Returned when no appointments exist in the system:

{
  "msg": "No hay turnos cargados en el sistema"
}

401 Unauthorized

Returned when the JWT token is missing or invalid:

{
  "msg": "Token inválido o no proporcionado"
}

500 Server Error

Returned when a server error occurs:

{
  "msg": "Error del servidor"
}

Automatic State Management

Before returning results, this endpoint automatically updates appointment states:

Identifies all appointments with state: "Pendiente"
Checks if the appointment date/time has passed:
- Appointments on dates before today
- Appointments today with time before current time
Updates matching appointments to state: "Ausente" (no-show)

This ensures the appointment list always reflects accurate, up-to-date statuses.

Use Cases

Dashboard View: Fetch all appointments with today’s statistics for a clinic dashboard
Professional Schedule: Filter by professionalID to show a doctor’s schedule
Patient Search: Use search parameter to quickly find a patient’s appointments by DNI
Status Management: Filter by state to view pending, completed, or cancelled appointments
Today’s Overview: Use appointmentsOfToday to display current day’s schedule

Authentication

Professionals

Patients

Appointments

Work Schedules

Specialties

Social Works

Get All Appointments

Overview

Authentication

Query Parameters

Response

Examples