Skip to main content
PUT
/
api
/
users
/
{userId}
/
reservations
/
{reservationId}
Update Reservation
curl --request PUT \
  --url https://api.example.com/api/users/{userId}/reservations/{reservationId} \
  --header 'Content-Type: application/json' \
  --data '
{
  "doctorId": 123,
  "patientId": 123,
  "timeBlockId": 123,
  "reason": "<string>",
  "notes": "<string>"
}
'
{
  "id": 123,
  "date": "<string>",
  "timeBlockId": 123,
  "patientId": 123,
  "doctorId": 123,
  "status": "<string>",
  "reason": "<string>",
  "notes": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

​
Authentication

This endpoint requires authentication. Include a valid JWT token in the Authorization header: 
Authorization: Bearer <token>

​
Path Parameters

​
userId
integer
required
The ID of the user who owns the reservation
​
reservationId
integer
required
The unique identifier of the reservation to update

​
Request Body

All fields are optional, but at least one field must be provided to update the reservation.
​
doctorId
integer
The ID of the doctor for the appointment. Must be a positive integer and the doctor must exist in the system.
​
patientId
integer
The ID of the patient for the appointment. Must be a positive integer and the patient must exist in the system.
​
timeBlockId
integer
The ID of the time block to reserve. Must be a positive integer, the time block must exist, and it cannot already be booked by another appointment (excluding the current appointment).
​
reason
string
The reason for the appointment. Maximum 255 characters. Can be empty or null.
​
notes
string
Additional notes for the appointment. Maximum 1000 characters. Can be empty or null.

​
Validation Rules

  • At least one field must be provided in the request body
  • doctorId: Optional, must be a positive integer if provided
  • patientId: Optional, must be a positive integer if provided
  • timeBlockId: Optional, must be a positive integer if provided
  • reason: Optional, maximum 255 characters
  • notes: Optional, maximum 1000 characters

​
Business Logic

The system performs the following validations before updating the reservation:
  1. Patient Exists: If patientId is provided, verifies it corresponds to an existing user
  2. Doctor Exists: If doctorId is provided, verifies it corresponds to an existing user
  3. Time Block Exists: If timeBlockId is provided, verifies it corresponds to an existing time block
  4. No Conflicts: If timeBlockId is provided, ensures the time block is not already reserved by a different appointment
When the time block is updated, the appointment date is automatically updated to match the new time block’s start time.

​
Response

​
id
integer
The unique identifier for the appointment
​
date
string
The appointment date and time (ISO 8601 format), automatically updated if timeBlockId changed
​
timeBlockId
integer
The ID of the associated time block
​
patientId
integer
The ID of the patient
​
doctorId
integer
The ID of the doctor
​
status
string
The appointment status: PENDING, CONFIRMED, CANCELLED, or COMPLETED
​
reason
string
The reason for the appointment
​
notes
string
Additional notes for the appointment
​
createdAt
string
Timestamp when the appointment was created (ISO 8601 format)
​
updatedAt
string
Timestamp when the appointment was last updated (ISO 8601 format)

​
Error Responses

​
400 Bad Request

Returned when validation fails or business rules are violated: 
{
  "error": "El paciente no existe"
}

{
  "error": "El doctor no existe"
}

{
  "error": "El bloque de tiempo no existe"
}

{
  "error": "Ya existe una reserva para este bloque de tiempo"
}

​
401 Unauthorized

Returned when the JWT token is missing or invalid: 
{
  "error": "Unauthorized"
}

​
Example Request

​
Update Time Block and Reason

curl -X PUT https://api.example.com/api/users/42/reservations/89 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "timeBlockId": 45,
    "reason": "Consulta de seguimiento"
  }'

​
Update Notes Only

curl -X PUT https://api.example.com/api/users/42/reservations/89 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "notes": "Paciente reporta mejoría en los síntomas"
  }'

​
Update All Fields

curl -X PUT https://api.example.com/api/users/42/reservations/89 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "doctorId": 7,
    "patientId": 12,
    "timeBlockId": 50,
    "reason": "Consulta especializada",
    "notes": "Transferido a especialista"
  }'

​
Example Response

{
  "id": 89,
  "date": "2026-03-16T14:30:00.000Z",
  "timeBlockId": 45,
  "patientId": 12,
  "doctorId": 5,
  "status": "PENDING",
  "reason": "Consulta de seguimiento",
  "notes": "Paciente presenta síntomas de gripe",
  "createdAt": "2026-03-03T14:30:00.000Z",
  "updatedAt": "2026-03-03T16:45:00.000Z"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us