Overview
The HTTP API you implement so Ovianta agents can work with your agenda.
The agenda integration lets an Ovianta agent read and change your agenda during a conversation. You expose a set of endpoints under one base URL, and Ovianta calls them as the conversation needs.
How it works
You give Ovianta a base URL
For example https://api.example.com/ovianta. Every endpoint path in these docs is appended to it, so POST /appointments means POST https://api.example.com/ovianta/appointments.
Ovianta generates a shared secret
When the integration is created, Ovianta generates a secret and shows it, with a copy button, in the integration's settings. Ovianta signs every request with it. See Authentication.
Ovianta reads your catalogs
It calls GET /custom-config to learn your doctors, specialties, insurances and centers. That is how a patient who says "the eye doctor" ends up as your specialityId. The "Test connection" button in Ovianta calls the same endpoint.
Agents call the other endpoints during conversations
A booking agent looks the patient up, asks for availability and books. A reminder agent lists the day's appointments, calls each patient and records whether they will come.
Endpoints
| Endpoint | What it is for |
|---|---|
GET /patients | Looks a patient up by NIF. Ovianta calls it before every other patient operation. |
POST /patients | Registers a new patient. Ovianta first checks with GET /patients that the NIF is not already registered. |
GET /availabilities | Free slots of one doctor, or of every doctor of a specialty, over a range of days. |
GET /appointments | Every appointment on one day. Used by reminder agents to know whom to call. |
GET /appointments/range (optional) | Every appointment on a list of days, in one call. If you answer 404, Ovianta calls GET /appointments?date= once per day instead. |
GET /appointments | A patient's appointments, by NIF or phone, optionally on one day. |
GET /appointments/{appointmentId} | One appointment by its id. |
POST /appointments | Books a slot the agent offered and the patient accepted. |
PUT /appointments/{appointmentId} | Moves an appointment to another day and time. |
DELETE /appointments/{appointmentId} | Cancels an appointment. |
POST /appointments/confirm | Records the patient's answer to a reminder: they will attend, or they will not. |
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. |
GET /custom-config | Your doctors, specialties, insurances and centers, so Ovianta can map what a patient says to your ids. |
Implement every endpoint not marked optional. An endpoint you do not implement makes the action that needs it fail.
Requests
- Format. JSON bodies with
Content-Type: application/json.GETandDELETEhave no body; their parameters go in the query string, URL-encoded. - Dates and times.
DD/MM/YYYYandHH:MM(24-hour), in the clinic's local time (Europe/Madrid). - Optional parameters are left out, never sent empty or as
null. - Speed matters. Most calls happen while a patient waits on the phone. Answer in well under a few seconds.
Responses
- Success is any
2xx. Use the status each endpoint lists; Ovianta does not reject a different2xx. - Ovianta reads only the fields documented for each endpoint and ignores the rest.
- Ovianta is lenient with values. Optional fields can be
nullor absent. Dates like1/3/2026or15-07-2026and times like9:00are accepted. One appointment with a bad phone number does not reject the whole list. - Ovianta is strict with shape. A missing required field, or a value of the wrong type, rejects the whole response and the action fails. See Errors.