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

Name	In	Type	Required	Description
phoneNumber	query	string	Yes	Phone 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": "4d59c916-9726-11ec-af3f-0a58a9feac02",
    "displayName": "Frodo Baggins",
    "dateOfBirth": "1971-07-09",
    "nhsNumber": "9693646525"
  }
]

400 Validation error: phoneNumber is missing.

Response fields

Field	Type	Description
errors[].code	string
errors[].description	string

{
  "errors": [
    {
      "code": "missing-phone-number",
      "description": "No phone number is specified"
    }
  ]
}