Patients API

import { Badge } from ‘@astrojs/starlight/components’;

Patients

GET /api/patients

List patients for the clinic with optional search.

Auth: Required

Query params:

Param	Description
`search`	ILIKE search on `full_name` and `phone`
`page`	Page number (default 1)
`limit`	Results per page (default 50)

Response 200:

{
  "patients": [
    {
      "id": "uuid",
      "full_name": "Juan Pérez",
      "phone": "+50377654321",
      "email": "juan@example.com",
      "no_show_count": 1,
      "is_blocked": false,
      "created_at": "2026-05-20T00:00:00Z"
    }
  ],
  "total": 82,
  "page": 1,
  "limit": 50
}

GET /api/patients/:id

Get a patient’s full record including appointment history.

Auth: Required

Response 200:

{
  "id": "uuid",
  "full_name": "Juan Pérez",
  "phone": "+50377654321",
  "email": "juan@example.com",
  "dui": "12345678-9",
  "notes": "Alergia a penicilina",
  "no_show_count": 1,
  "is_blocked": false,
  "appointments": [
    {
      "id": "uuid",
      "appointment_date": "2026-06-15",
      "start_time": "14:00:00",
      "status": "confirmed",
      "doctors": {
        "full_name": "Dr. García",
        "specialty": "Medicina General"
      }
    }
  ]
}

Notes:

dui is decrypted and returned only to admin role users. Staff see null.

GET /api/patients/export

Export all patients as a CSV file.

Auth: Required

Response 200:

Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="pacientes.csv"

CSV columns: Nombre, Teléfono, Email, Registrado

Errors:

Status	Code
`403`	`PLAN_UPGRADE_REQUIRED`

POST /api/patients/import

Import patients from a CSV file.

Auth: Required

Request: multipart/form-data, field name file, max 5 MB

CSV column names (case-insensitive, accepts Spanish and English variants):

Data	Accepted column names
Name	`nombre`, `name`, `full_name`
Phone	`telefono`, `phone`
Email	`email`
DUI	`dui`

Response 200:

{ "message": "Successfully imported 42 patients" }

Patients are upserted on (clinic_id, phone). Existing records are updated, new ones are created.

Errors:

Status	Code
`400`	Invalid CSV format or missing required column
`403`	`PLAN_UPGRADE_REQUIRED`

PATCH /api/patients/:id/block

Block or unblock a patient from chatbot interaction.

Auth: Required

Request:

{ "blocked": true }

When is_blocked = true, the WhatsApp chatbot silently ignores all messages from this patient.

Response 200: Updated patient object