Getting started

How to get access

Salud en Ruta enables API access for each provider under contract. There is no public sign-up: this way we make sure every key belongs to an organisation we have a data processing agreement with.

1. Request access by emailing the technical team (info@saludenruta.es) with your organisation's name, a technical contact and, if you already have it, the URL where you want to receive sandbox webhooks.
2. We give you a test key (srd_test_…) and enable your sandbox, with the same service catalogue as your contract and fictitious data. If you gave us a URL, you also get the webhook secret (whsec_…).
3. Build and test against the sandbox as much as you need: there is no cost and no risk, and visits move forward on their own thanks to the simulator.
4. We validate the integration with you using the go-live checklist: creating visits, cancelling, receiving and verifying webhooks, error handling.
5. We give you the production key (srd_live_…) and the production webhook secret. From then on every visit is real: it reaches the dispatch centre and a unit goes out.

Your first integration in 5 minutes

You need your test key and, for the last step, a public URL to receive webhooks (for testing, a service like webhook.site or a tunnel such as ngrok to your machine will do). The examples use curl; the code samples cover the same steps in JavaScript, Python, PHP, Java and C#.

Store the key in an environment variable so you don't have to type it in every command:

export SERAD_API_KEY="srd_test_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
export SERAD_API_URL="https://sandbox-api.saludenruta.es/api/integrations/v1"

1. Read your catalogue

The catalogue tells you which service types you can request and whether your contract requires a case number:

curl "$SERAD_API_URL/catalog" \
  -H "X-Api-Key: $SERAD_API_KEY"

{
  "status": 200,
  "data": {
    "providerType": "INSURER",
    "requiresExternalRef": true,
    "serviceTypes": [
      { "id": "57605fe9-bade-4040-b403-5eeb58e57c9e", "code": "GENERAL_CONSULTATION", "name": "Consulta general", "requiredProfessional": "DOCTOR" },
      { "id": "0c7f3a52-3f1d-4b8e-9d6a-2f4b5c6d7e8f", "code": "NURSING_CARE", "name": "Curas de enfermería", "requiredProfessional": "NURSE" }
    ],
    "insurers": []
  },
  "message": "Se ha obtenido el catálogo"
}

If you get a 401, check the key and make sure you're using the sandbox URL with an srd_test_… key (environments).

2. Create a visit

Use the code of one of your service types and send a unique Idempotency-Key (if the request is interrupted and you repeat it with the same key, no duplicate visit is created):

curl -X POST "$SERAD_API_URL/visits" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: primeros-pasos-0001" \
  -d '{
    "patient": {
      "firstName": "María",
      "lastName": "García López",
      "documentType": "DNI",
      "documentNumber": "12345678Z",
      "birthDate": "1948-05-17",
      "phone": "+34600111222"
    },
    "address": {
      "line1": "Calle de Alcalá 120",
      "line2": "3º B",
      "city": "Madrid",
      "postalCode": "28009"
    },
    "serviceTypeCode": "GENERAL_CONSULTATION",
    "priority": "URGENT",
    "reason": "Fiebre alta desde ayer, 39 ºC",
    "externalRef": "EXP-2026-004512"
  }'

The response (201 Created) is the visit, with its id and its human-readable code (AV-000123):

{
  "status": 201,
  "data": {
    "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
    "code": "AV-000123",
    "status": "PENDING",
    "statusLabel": "Pendiente",
    "priority": "URGENT",
    "origin": "PROVIDER_API",
    "externalRef": "EXP-2026-004512",
    "serviceType": { "id": "57605fe9-bade-4040-b403-5eeb58e57c9e", "code": "GENERAL_CONSULTATION", "name": "Consulta general" },
    "requiredProfessional": "DOCTOR",
    "patientName": "María García López",
    "address": { "line1": "Calle de Alcalá 120", "city": "Madrid", "postalCode": "28009" },
    "estimatedMinutes": 60,
    "milestones": { "requestedAt": "2026-10-01T09:10:00.000Z", "assignedAt": null, "departedAt": null, "arrivedAt": null, "finishedAt": null, "cancelledAt": null, "invoicedAt": null },
    "cancellable": true,
    "reportAvailable": false
  },
  "message": "Se ha creado el aviso"
}

Keep the id: it identifies the visit in every other call.

3. Retrieve the visit

In the sandbox, the simulator moves the visit forward on its own every 20 seconds: assigned, en route, on site and finished. Check its status:

curl "$SERAD_API_URL/visits/c6a3c348-40b6-4158-a44a-7d85f01a0201" \
  -H "X-Api-Key: $SERAD_API_KEY"

You'll see status, the milestones (the time of each milestone) and the timeline change. In a real integration you wouldn't poll like this: that's what webhooks are for.

4. Receive your first webhook

Ask the technical team to register your sandbox URL for the events you're interested in (usually all of them). We'll give you a whsec_… secret to verify the signature. From then on, every status change on your visits reaches your URL as a POST:

POST /serad/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: SaludEnRuta-Webhooks/1.0
X-Serad-Event: visit.assigned
X-Serad-Delivery: 9b2f0c4e-1a7d-4e3b-8f6a-5c4d3b2a1f0e
X-Serad-Timestamp: 1790846100
X-Serad-Signature: sha256=5d1c…e9a0

{"id":"6f0a9c1e-2b7d-4f8a-9e3c-1d2b3c4d5e6f","type":"visit.assigned","createdAt":"2026-10-01T09:15:00.000Z","data":{"visit":{"id":"c6a3c348-40b6-4158-a44a-7d85f01a0201","code":"AV-000123","status":"ASSIGNED", …}}}

Create another visit and check that you receive visit.created, visit.assigned, visit.en_route, visit.on_site and visit.finished. Your receiver must respond with a 2xx within 10 seconds; otherwise, we retry.

What's next

• Read the visits guide to learn about every field, the priorities and scheduled appointments.
• Implement webhook signature verification and deduplication.
• Handle errors and rate limits.
• Run through the recommended scenarios before asking for your production key.