Introduction to the integration API

What it is

The Salud en Ruta provider integration API lets an insurer, an intermediary or a healthcare platform (a telemedicine service, for example) request home visits from a doctor or a nurse straight from its own system and follow their progress without picking up the phone or using the portal.

It is a REST API over HTTPS that speaks JSON, versioned in the path (/v1), with key-based authentication, standard error responses (RFC 9457) and signed webhooks that tell you about every status change the moment it happens.

Who it is for

• Insurers that request and pay for their own visits.
• Intermediaries (assistance companies, service hubs) that work for several insurers and must state the patient's end insurer on every visit.
• Healthcare platforms (telemedicine providers such as Teladoc) that need a professional to visit the patient at home after a video consultation.

If you only send a handful of visits a day, the provider portal (linked from the footer of this site) may be all you need: it does the same as the API, with no code.

What you can do

• Read your catalogue: the service types in your contract, which professional each one needs (doctor or nurse), whether you must send a case number and, if you are an intermediary, the insurers you work for. → Catalogue
• Create visits — urgent, standard or scheduled — with the patient's details, the address and the reason. → Visits
• Retrieve a visit (status, milestones and timeline) or list yours with filters and pagination. → Visits
• Get the estimated arrival time while the unit is on its way. → Visits
• Cancel a visit free of charge as long as the unit has not set off. → Visits
• Download the care report as a PDF once the professional has signed it and the patient has consented to sharing it. → Visits
• Receive webhooks in your system for every status change, invoicing included. → Webhooks
• Test everything in an isolated environment with fictitious data and a simulator that moves visits forward. → Sandbox

How a visit works

A visit is a request for a healthcare professional to see a patient at home. When you create it, it starts as PENDING; the Salud en Ruta dispatch centre assigns it to a unit (medical or nursing), the unit sets off, arrives, sees the patient and closes the visit. Salud en Ruta then validates it and includes it in your invoice.

1. CreatedPENDINGvisit.created
2. AssignedASSIGNEDvisit.assigned
3. On the wayEN_ROUTEvisit.en_route
4. On siteON_SITEvisit.on_site
5. FinishedFINISHEDvisit.finished
6. ValidatedVALIDATEDno webhook
7. InvoicedINVOICEDvisit.invoiced

Cancelled CANCELLED · visit.cancelled
Through the API a visit can be cancelled while PENDING or ASSIGNED, free of charge. Once the unit is on its way or on site, only the dispatch centre can cancel it (by phone).

In addition, report.shared is sent when the care report becomes available to you.

What the API does not do

• It does not handle emergencies. Salud en Ruta provides home care for non-life-threatening urgent cases. In a life-threatening emergency, the patient must call 112. Never send visits that need an ambulance through the API.
• It does not return clinical data. No symptoms, diagnosis or treatment: clinical information is only available in the care report, and only with the patient's consent. Nor does it return details about the professionals or the unit's location. → Patients and privacy
• It does not modify existing visits. If you get something wrong, cancel the visit (while you still can) and create a new one, or call the dispatch centre.
• It does not cancel visits once the unit is on its way. From EN_ROUTE onwards, only the dispatch centre can do that, by phone (+34 611 673 280).
• It does not manage keys or webhooks. API keys and webhook URLs are set up by Salud en Ruta from its intranet; ask the technical team.
• It is not meant for the browser. The API key is secret: always make calls from your server, never from a website or a mobile app.

Next step

Start with the getting started guide: in five minutes you'll have created a test visit and received your first webhook.