Patients and privacy · Developer API

The API handles health data, which the GDPR treats as a special category (Art. 9). This guide explains which patient data we receive, which we return to you and why the API is designed to return as little as possible.

How we identify patients

Every visit is for a patient. So that the professional visiting the home has their history (allergies, previous visits, treatments), we try to recognise whether the patient already exists in Salud en Ruta:

With the document type and number (DNI, NIE or PASSPORT) and date of birth, we look for a record with exactly those three items. If there is one, the visit is linked to it; if not, a new record is created.
With documentType: "NONE" (minors without an ID card, or patients who don't provide one) there's no reliable way to tell whether it's the same person, so a new record is always created. If the dispatch centre later spots that it was a known patient, it merges the records internally.
DNI and NIE numbers are validated (format and check letter) before the lookup: a mistyped document returns 400 and creates no record.

We only return what you sent

Whether a document matches an existing record is an internal matter: we don't tell you, and the response is identical whether or not the patient already exists. Specifically:

patientName is the name exactly as you sent it for that visit, never the one on our record. If you send a DNI that matches a record with a different name, you'll see your name, and the dispatch centre will review the case.
We don't return the date of birth, document, phone number or full address from our record. The visit address (address) is returned without the floor, the access notes or the coordinates.
There's no endpoint to look up patients by document or to list patients.

That way, the API can't be used to find out whether someone is a Salud en Ruta patient or to obtain data you didn't already have: with your key you only see what your organisation already knew.

What we never return

Data	Why not
Symptoms, examination, diagnosis, treatment, prescriptions	They're clinical data. They're only available in the care report, with consent.
The reason (`reason`) you sent	It's health data: we don't echo it in responses or webhooks. You already have it in your system.
Names, licence plates or phone numbers of professionals and vehicles	They're personal data of our staff. We only tell you the unit type (medical or nursing).
The unit's location	Only the estimated arrival time.
Other providers' data	Each key only sees its own organisation's visits; someone else's visit returns `404`, as if it didn't exist.
Internal amounts	Billing goes through its own channel (portal and invoices). Webhooks only carry the invoice number.

Webhooks are even leaner: they carry no patient data at all (not even the name), only identifiers, statuses, times and your externalRef. See the payload.

Roles. For the visits you send us, your organisation and Salud en Ruta sign an agreement that sets out who is the controller for each processing activity. The API doesn't change that agreement; it's just the channel.
Data minimisation. Only send what's needed for the visit: identification, contact details, address and reason. Don't send full medical records, policies or third-party data in reason or accessNotes.
Accuracy. Check the data before sending it: a wrong phone number or floor delays the visit and forces the unit to call.
Security on your side. Whatever you receive (above all, reports) must be stored with the safeguards the GDPR requires for health data: restricted access, encryption and access logging.
Access logging. Salud en Ruta logs every access to clinical data, including every report download through the API, together with the key that made it.
Sandbox. The sandbox is for fictitious data only. Don't send real patient data to the test environment, not even to reproduce a problem: if you need to look into a real case, email us with the visit code (AV-…) and we'll check it in production.

The care report (what the professional writes and signs after the visit) is the only clinical data you can obtain through the API, and only when all three conditions are met:

The professional has signed the report.
Salud en Ruta has shared it with your organisation.
The patient has consented to it being sent to you.

If any of them is missing, GET /visits/{id}/report returns 404 (/errors/provider/report-not-available), without saying which one fails. When the report becomes available you receive the report.shared webhook and reportAvailable changes to true.

Every download is logged. Download it once, store it in your document system and serve it from there; don't request it from the API every time someone looks at it. Technical details in visits.

Something missing or not matching what you see? Email our technical team: info@saludenruta.es.

How we identify patients

We only return what you sent

What we never return

Health data and the GDPR

Reports only with consent