Skip to main content
POST
/
api
/
appointments
Create Appointment
curl --request POST \
  --url https://api.example.com/api/appointments \
  --header 'Content-Type: application/json' \
  --data '
{
  "patient_id": "<string>",
  "doctor_id": "<string>",
  "date": "<string>",
  "time": "<string>",
  "duration_minutes": 123,
  "reason": "<string>",
  "notes": "<string>",
  "send_notification": true
}
'
{
  "id": "<string>",
  "patient_id": "<string>",
  "patient_name": "<string>",
  "doctor_id": "<string>",
  "doctor_name": "<string>",
  "specialty": "<string>",
  "date": "<string>",
  "time": "<string>",
  "duration_minutes": 123,
  "status": "<string>",
  "reason": "<string>",
  "notes": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DUVAN100/saludya-api/llms.txt

Use this file to discover all available pages before exploring further.

Create a new appointment in the system. The appointment will be created with a scheduled status by default.

​
Request Body

​
patient_id
string
required
ID of the patient for this appointment
​
doctor_id
string
required
ID of the doctor who will attend the appointment
​
date
string
required
Date of the appointment in ISO 8601 format (YYYY-MM-DD)
​
time
string
required
Time of the appointment in 24-hour format (HH:MM)
​
duration_minutes
integer
default:"30"
Expected duration of the appointment in minutes
​
reason
string
required
Reason for the appointment visit
​
notes
string
Additional notes or special instructions for the appointment
​
send_notification
boolean
default:"true"
Whether to send confirmation notification to the patient

​
Response

​
id
string
Unique appointment identifier
​
patient_id
string
ID of the patient
​
patient_name
string
Full name of the patient
​
doctor_id
string
ID of the assigned doctor
​
doctor_name
string
Full name of the doctor
​
specialty
string
Medical specialty for the appointment
​
date
string
Appointment date (ISO 8601 format)
​
time
string
Appointment time (HH:MM format)
​
duration_minutes
integer
Expected duration of the appointment in minutes
​
status
string
Current status of the appointment (will be scheduled for new appointments)
​
reason
string
Reason for the appointment visit
​
notes
string
Additional notes or special instructions
​
created_at
string
Timestamp when the appointment was created
​
updated_at
string
Timestamp when the appointment was last updated

​
Example Request

curl -X POST "https://api.saludya.com/api/appointments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "pat_5x8y2z4a6b",
    "doctor_id": "doc_3j5k7m9n1p",
    "date": "2026-03-15",
    "time": "14:30",
    "duration_minutes": 30,
    "reason": "Consulta de seguimiento",
    "notes": "Paciente reporta dolor en el pecho",
    "send_notification": true
  }'

​
Example Response

{
  "id": "apt_9n5p2r6t8v",
  "patient_id": "pat_5x8y2z4a6b",
  "patient_name": "María González",
  "doctor_id": "doc_3j5k7m9n1p",
  "doctor_name": "Dr. Carlos Ramírez",
  "specialty": "Cardiología",
  "date": "2026-03-15",
  "time": "14:30",
  "duration_minutes": 30,
  "status": "scheduled",
  "reason": "Consulta de seguimiento",
  "notes": "Paciente reporta dolor en el pecho",
  "created_at": "2026-03-06T10:30:45Z",
  "updated_at": "2026-03-06T10:30:45Z"
}

​
Error Responses

​
error
object
​
code
string
Error code identifier
​
message
string
Human-readable error message
​
details
object
Additional error details (when applicable)

​
400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "date": "Date must be in the future",
      "time": "Time must be in HH:MM format"
    }
  }
}

​
401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API token"
  }
}

​
404 Not Found

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Patient with ID 'pat_5x8y2z4a6b' not found"
  }
}

​
409 Conflict

{
  "error": {
    "code": "APPOINTMENT_CONFLICT",
    "message": "Doctor is not available at the requested time",
    "details": {
      "conflicting_appointment_id": "apt_7k3m9n2p4q",
      "suggested_times": ["15:00", "15:30", "16:00"]
    }
  }
}

​
422 Unprocessable Entity

{
  "error": {
    "code": "INVALID_TIME_SLOT",
    "message": "Appointment time must be during doctor's working hours (09:00-17:00)"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us