Appointments
List, search, read, book, move, cancel and confirm appointments.
Every endpoint under /appointments.
Listing and searching
GET /appointments answers two kinds of query on the same route. Tell them apart by the parameters:
- With
niforphone: one patient's appointments, optionally limited to one day bydate. See Search a patient's appointments. - With only
date: every appointment that day. See List a day's appointments.
Both answer with the same list of appointments. In both cases, leave out cancelled appointments.
List a day's appointments
GET/appointments
Every appointment on one day. Used by reminder agents to know whom to call.
Query parameters
Prop
Type
Response: 200
Prop
Type
Example request
GET {baseUrl}/appointments?date=16/02/2026¢erId=1
Accept: application/json
X-Signature: 5f2b9c…Example response
{
"data": [
{
"appointmentId": "56834",
"date": "16/02/2026",
"time": "10:00",
"doctorId": "24895",
"doctorName": "Dr. Juan Pérez",
"patientId": "345345",
"nif": "33557799V",
"patientName": "Marta Ruiz",
"phone": "+34654654654",
"reason": "Revisión ocular",
"centerRef": "1",
"extraData": {
"room": "3B"
}
}
]
}List several days' appointments
GET/appointments/rangeOptional
Every appointment on a list of days, in one call. If you answer 404, Ovianta calls GET /appointments?date= once per day instead.
Query parameters
Prop
Type
Response: 200
Prop
Type
Example request
GET {baseUrl}/appointments/range?dates=16/02/2026,17/02/2026,19/02/2026
Accept: application/json
X-Signature: 5f2b9c…Example response
{
"data": [
{
"appointmentId": "56834",
"date": "16/02/2026",
"time": "10:00",
"doctorId": "24895",
"doctorName": "Dr. Juan Pérez",
"patientId": "345345",
"nif": "33557799V",
"patientName": "Marta Ruiz",
"phone": "+34654654654",
"reason": "Revisión ocular",
"centerRef": "1",
"extraData": {
"room": "3B"
}
},
{
"appointmentId": "56901",
"date": "19/02/2026",
"time": "12:30",
"doctorId": "24895",
"doctorName": "Dr. Juan Pérez",
"patientId": "789012",
"nif": "44668800X",
"patientName": "Ana García",
"phone": "+34655655655",
"reason": "Control postoperatorio",
"centerRef": "2",
"extraData": null
}
]
}Search a patient's appointments
GET/appointments
A patient's appointments, by NIF or phone, optionally on one day.
Query parameters
Prop
Type
Response: 200
Prop
Type
Example request
GET {baseUrl}/appointments?nif=33557799V&phone=+34654654654
Accept: application/json
X-Signature: 5f2b9c…Example response
{
"data": [
{
"appointmentId": "56834",
"date": "16/02/2026",
"time": "10:00",
"doctorId": "24895",
"doctorName": "Dr. Juan Pérez",
"patientId": "345345",
"nif": "33557799V",
"patientName": "Marta Ruiz",
"phone": "+34654654654",
"reason": "Revisión ocular",
"centerRef": "1",
"extraData": {
"room": "3B"
}
}
]
}Without date, return the patient's appointments from today on.
Get an appointment
GET/appointments/{appointmentId}
One appointment by its id.
Path parameters
Prop
Type
Response: 200
Prop
Type
Example request
GET {baseUrl}/appointments/56834
Accept: application/json
X-Signature: 5f2b9c…Example response
{
"appointmentId": "56834",
"date": "16/02/2026",
"time": "10:00",
"doctorId": "24895",
"doctorName": "Dr. Juan Pérez",
"patientId": "345345",
"nif": "33557799V",
"patientName": "Marta Ruiz",
"phone": "+34654654654",
"reason": "Revisión ocular",
"centerRef": "1",
"extraData": {
"room": "3B"
}
}Booking and changing
Create an appointment
POST/appointments
Books a slot the agent offered and the patient accepted.
Request body
Prop
Type
Response: 201
Prop
Type
Example request
POST {baseUrl}/appointments
Content-Type: application/json
Accept: application/json
X-Signature: 5f2b9c…
{
"date": "16/02/2026",
"time": "16:00",
"doctorId": "24895",
"specialityId": "1",
"patientId": "345345",
"reason": "Revisión ocular",
"centerId": "1",
"insuranceId": "23507325"
}Example response
{
"appointmentId": "56834"
}The slot comes from your own GET /availabilities answer, but another patient may have taken it in between. If so, answer 409 with a code such as SLOT_NOT_AVAILABLE, and the agent offers another slot.
Reschedule an appointment
PUT/appointments/{appointmentId}
Moves an appointment to another day and time.
Path parameters
Prop
Type
Request body
Prop
Type
Response: 200
Prop
Type
Example request
PUT {baseUrl}/appointments/56834
Content-Type: application/json
Accept: application/json
X-Signature: 5f2b9c…
{
"newDate": "18/02/2026",
"newTime": "09:30"
}Example response
{
"appointmentId": "56834"
}If your system moves an appointment by creating a new one, return the new id.
Cancel an appointment
DELETE/appointments/{appointmentId}
Cancels an appointment.
Path parameters
Prop
Type
Response: 204
No body is read.
Example request
DELETE {baseUrl}/appointments/56834
Accept: application/json
X-Signature: 5f2b9c…If the appointment was already cancelled, answer 409 with APPOINTMENT_ALREADY_CANCELLED. See Expected refusals.
Confirmations
Confirm an appointment
POST/appointments/confirm
Records the patient's answer to a reminder: they will attend, or they will not.
Request body
Prop
Type
Response: 200
Prop
Type
Example request
POST {baseUrl}/appointments/confirm
Content-Type: application/json
Accept: application/json
X-Signature: 5f2b9c…
{
"appointmentId": "56834",
"confirmed": true
}Example response
{
"status": "confirmed"
}Confirming twice is not an error: answer { "status": "alreadyConfirmed" }. If the appointment no longer exists, answer 404 with APPOINTMENT_NOT_FOUND.
End of a reminder cycle
POST/appointments/end-of-reminder-day
A reminder agent finished its cycle for a day. Use it to act on the appointments that never confirmed.
Request body
Prop
Type
Response: 200
No body is read.
Example request
POST {baseUrl}/appointments/end-of-reminder-day
Content-Type: application/json
Accept: application/json
X-Signature: 5f2b9c…
{
"voiceAgentConfigId": "6801234abcde5f6789012345",
"date": "16/02/2026",
"executionDate": "15/02/2026",
"dates": [
"16/02/2026",
"17/02/2026"
],
"centerId": "1",
"skipAppointmentIds": [
"56901"
]
}Leave every appointment in skipAppointmentIds untouched. They were added to the day after the cycle started, and the agent has not finished trying to reach those patients. See Reminders for where this call fits.