Service catalogue

What it is for

The catalogue answers the question "what can I request?" for your contract. Before creating visits, your integration should read it to find out:

• which service types are available to you (general consultation, urgent care, paediatrics, nursing…) and which professional each one requires;
• whether your contract requires a case number on every visit;
• if you're an intermediary, which end insurers you can send visits for.

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

It requires the visits:write scope (which is what whoever creates visits needs).

The response

{
  "status": 200,
  "data": {
    "providerType": "INTERMEDIARY",
    "requiresExternalRef": true,
    "serviceTypes": [
      { "id": "57605fe9-bade-4040-b403-5eeb58e57c9e", "code": "GENERAL_CONSULTATION", "name": "Consulta general", "requiredProfessional": "DOCTOR" },
      { "id": "9a1e4c3b-7d2f-4b6a-8e5c-3f2d1c0b9a87", "code": "PEDIATRICS", "name": "Pediatría", "requiredProfessional": "DOCTOR" },
      { "id": "0c7f3a52-3f1d-4b8e-9d6a-2f4b5c6d7e8f", "code": "NURSING_CARE", "name": "Curas de enfermería", "requiredProfessional": "NURSE" }
    ],
    "insurers": [
      { "id": "fe8faeb8-0051-40d5-b0c1-dce10d5f5ba1", "name": "Aseguradora Ejemplo" },
      { "id": "2b7c9d1e-4f3a-4c8b-a6d5-e9f8c7b6a5d4", "name": "Mutua Ejemplo" }
    ]
  },
  "message": "Operación realizada correctamente"
}

Service types and required professional

The service types you see are the ones priced in your current rate card. If you request one that isn't in your catalogue, the request returns 400 with the type /errors/provider/service-type-not-allowed. If you need a service that isn't listed, talk to us: it's a contract change, not an integration change.

requiredProfessional tells you which kind of unit will visit the patient:

• DOCTOR: medical unit (doctor and driver). Consultations, non-life-threatening urgent care, paediatrics…
• NURSE: nursing unit. Wound care, injections, check-ups, removal of stitches or catheters…

Use it to guide whoever creates the visit in your system (for example, so they aren't offered "wound care" when the reason is "high fever"). Once the visit is assigned, the webhook and the visit itself state the unit type (unitType / unit.type: MEDICAL or NURSING).

End insurers (intermediaries)

If you're an intermediary (providerType: "INTERMEDIARY"), you work for several insurers and each visit is for a policyholder of one of them. State it in the request with insurerId, taken from insurers[]:

{
  "insurerId": "fe8faeb8-0051-40d5-b0c1-dce10d5f5ba1",
  "serviceTypeCode": "GENERAL_CONSULTATION",
  "…": "…"
}

• The insurerId must be one of your insurers; otherwise, 400 with the type /errors/provider/insurer-not-managed.
• If you aren't an intermediary, don't send insurerId: you'll get the same 400.
• Insurer id values differ between environments. Read them from each environment's catalogue (by name) instead of copying them.

Required case number

If requiresExternalRef is true, your contract requires every visit to carry your case number (externalRef, up to 100 characters). Without it, the request returns 400 with the type /errors/visits/external-ref-required.

Even when it isn't required, we recommend always sending it: it links the visit to your system, appears on your invoices, in webhooks and in the portal, and lets you find the visit with GET /visits?externalRef=… without storing our id.

How often to read it

The catalogue rarely changes (only when your rate card or your insurers change). A sensible approach is to:

• read it at startup and cache it;
• refresh it once a day;
• and read it again if a request returns service-type-not-allowed or insurer-not-managed, in case it has changed.

There's no need to read it before every request.