API integration

The Turno Virtual API lets other systems work with your account automatically: for example, your clients can book from your own website or app, or your organization's management software can read your schedule. If you are just getting started, first read what Turno Virtual is.

Access and plans

Each access key has one or more options under Access, and each option enables a different use of the API:

The healthcare plans include the same access as their equivalent plan. You can see the plans on the home page.

Bookings

With Bookings, your website or app can offer the same as the online booking on your microsite, with the same rules: your clients see the same free times, book with the same details and can cancel their appointment. Appointments booked this way appear in your schedule as Requested, and your client receives the same email notice as on the microsite.

API bookings also follow the Maximum requests per hour set in Settings › Company, Appointment tab. If your site repeats a booking that was already made, the response says your client already has that time, and the appointment isn't booked twice.

Management

With Management, your management system can read your schedules, with their branch, their professionals and their services, and their appointments, with their time, their status and the client's details. It sees all appointments, including Canceled ones, so it stays up to date with cancellations.

It can also look up a schedule's free times, over a range of up to 31 days: the same ones the Schedule offers you when you book an appointment, including the ones in time ranges your clients don't see online, such as Private ones. This way your system can look for a time before booking the appointment. If it names a service or a procedure, the free times are offered with the duration of that service or procedure.

An account key sees all schedules. A personal key sees the same as that person sees in the Schedule: for a Professional, only the schedules assigned to them.

Besides reading, a personal key of someone with the Book appointments permission can change the status of appointments: set them to Assigned (what Assign, Back to assigned and Activate do), Waiting, Attended or Canceled, only through the steps in the table in appointment states. A note can go with the change, and it is added to the appointment's Notes. If the appointment already has that status, nothing changes, not even the notes.

With the same permission, that key can also book appointments, like New appointment in the schedule: one or several times at once for the same client, up to 52 in a single request, including overbooked appointments. Medical As in the schedule, each appointment carries its coverage, and its procedure if the schedule asks for one. Either all of them are booked or none is: if any time is taken or the schedule doesn't work at that time, none is booked and the response says which ones have to change. A client can't have two overlapping appointments in the same schedule: if your system repeats a request that was already booked, the response says the client already has those times, and none is booked twice. Each new appointment is Assigned.

A personal key of someone with the Edit appointments permission can move an appointment to another day or time, or change its duration, within the same schedule. As when you move it from Edit, the new time must be free and within the schedule's hours.

Your system also sees each schedule's blocked times: the Block time events, with their type (Leave, Meeting or Other), their time and their notes. Events are kept apart from appointments: they don't appear in the list of appointments, and appointments don't appear in the list of events. A personal key of someone with the Assign events permission can also block a time in one of the schedules that person sees, like Block time; change an event's time, type or notes, like Edit block, within the same schedule (to move it to another schedule, delete it and add it again there); and delete it, like Delete. An event can't overlap with appointments or with another event in that schedule (overbooked appointments don't count: an event can sit on top of one): if the time has any, it isn't blocked, and those appointments have to be canceled first. While the event exists, that time isn't offered for booking, either online or from your system.

That key only books, moves and changes appointments in the schedules that person sees, and everything is recorded the same as if they did it from the portal: it appears under that person's name in the appointment's Activity, and your client receives the same emails, such as the one for a new appointment or for a change of time. An account key can only read: it can't book or move appointments, change their status or block times.

Create an access key

Each system that connects uses its own key. Administrator manages the account keys from the settings menu (the gear), in Integrations › API keys.

To create a key, enter a Name that helps you recognize which system uses it and check its Access options. Only the access your plan includes is offered.

When you save, the full key appears only once, with a button to copy it. Copy it and keep it in a safe place: you can't see it again afterwards. It looks like vit_<prefix>_<secret>, and anyone who has it can use the API on behalf of your account. Each person on the team can also create their own personal keys (see below).

In the list of keys you see when each one was created, its name, the User who owns the key, the beginning of the key, its access and when it was Last used. Account keys have no User; the ones that have one are personal keys of someone on your team. Apps someone connected by signing in from them, such as an AI assistant, don't appear here: they belong to that person, who sees and disconnects them in My profile, Connected apps tab.

Change or delete a key

You can edit an account key's name and access whenever you want. Personal keys can't be edited: you can only delete them. If you remove all its access options, the key stops working without being deleted.

If you think a key was leaked, or the system that used it no longer connects, delete it: it stops working right away. To replace it, create a new key, enter it in the other system and then delete the old one.

Personal keys

Besides the account keys, anyone on the team can create their own keys to connect their tools. A personal key acts on behalf of that person and with their role's permissions, and only in the account where they created it: if you work in more than one account, each one has its own keys.

To create one, open My profile (your photo, top right) and go to the API keys tab. The tab shows which account the keys you see belong to. Click New key, enter a Name, check its Access options and save it: as with account keys, only the access your plan includes is offered, and the full key appears only once, so copy it right then.

For Bookings, a personal key works the same as an account key: it books and cancels appointments the way online booking does, not as a person on the team.

In the same tab you see your keys with their access and when they were Last used, and you can delete the ones you no longer use.

Administrator sees all personal keys in Integrations › API keys, with their User, and can delete any of them, but can't create keys on behalf of another person: New there always creates an account key.

A personal key stops working if:

• you or Administrator delete it;
• that person's Status in Administration › Users is changed so they can no longer sign in (it works again if they are reactivated);
• that person is removed from the account: in that case their personal keys are deleted with them.

For the developer building the connection

Everything the person who programs the connection needs to know (how to send the key, which queries there are and what each one returns) is in the OpenAPI document, which can be opened without a key at turnovirtual.com/api/v1/openapi.json. Most development tools can import it to generate the connection code.