Skip to main content
GET/transactional-api/caller-id-lookup

Caller ID Lookup

Looks up patients by phone number. Returns all patients whose registered phone number matches, plus patients linked to a matching registered carer or contact. Suitable for inbound call identification.

Authorization: Bearer token (JWT). See Authentication.

Request​

curl -L -X GET 'https://{tenantId}.api.england.medicus.health/transactional-api/caller-id-lookup' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'

Path and query parameters

NameInTypeRequiredDescription
phoneNumberquerystringYesPhone number to look up. Accepts national (e.g. 07700 900000) or international (e.g. +447700900000) format.

Responses​

200 Matching patients, sorted by family name then given name. Returns an empty array when no patients match.
[
  {
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "displayName": "string",
    "dateOfBirth": "2025-01-01",
    "nhsNumber": "string"
  }
]
400 Validation error: phoneNumber is missing.
{
  "errors": [
    {
      "code": "missing-phone-number",
      "description": "No phone number is specified"
    }
  ]
}