Search patients by phone number

Look up the patients on a phone number, with their active packs and the clinic's catalog.

GET /v2/patients/search-by-phone

The lookup you run before booking: who is registered on this number, what packs do they already own, and what could they buy. It returns exactly the payload verify-phone-verification-otp does, so use this when the gate is already open and you just need the data again.

OTP-gated

The gate must be open for the same x-end-user-id — this reads patient records, so it requires the consent check even though it changes nothing.

Query parameters

Name	Type	Required	Description
`phoneNumber`	string	Yes*	The number, without the dial code.
`countryCode`	string	No	Defaults to `+91`.
`email`	string	Yes*	*An alternative to the phone pair. When both are sent, the email wins and the phone is ignored.

Try it

GET/v2/patients/search-by-phone🔒 OTP

OTP-gated: the verified phone is the scope, so an API key must run the OTP pair first with the same x-end-user-id.

API key*

Sent as x-api-key. Shared by every Try block on this page.End-user ID*Your id for the patient, sent as x-end-user-id. Keep it identical across send, verify and the gated call.

Query

Country code*Phone number*

Request

GET /v2/patients/search-by-phone?countryCode=%2B91&phoneNumber=9811100001

to https://api.medos.one

Use a dedicated test key, and put your browser's address on its allowlist

A Developer API key authenticates on its own, so it only works from the addresses registered against it — and this page calls from your browser, not your servers. Unless your own public address is on the list you get a 403 naming it, which is the allowlist doing its job. Your browser may also reach us over IPv6 even when your server does not, so the address in the error is often not the one you expected. The key here is kept in memory only and never written to storage, but create a test key for it and deactivate that key when you are done.

Request

curl -sG "https://api.medos.one/v2/patients/search-by-phone" \
  -H "x-api-key: $MEDOS_API_KEY" \
  -H "x-end-user-id: $PATIENT_ID" \
  --data-urlencode "countryCode=+91" \
  --data-urlencode "phoneNumber=9876543210"

Response

{
  "success": true,
  "message": "Patient search completed successfully",
  "data": {
    "associatedPatients": [
      {
        "id": 774,
        "mrnNumber": "MRN-0774",
        "firstName": "Asha",
        "lastName": "Nair",
        "countryCode": "+91",
        "phoneNumber": "9876543210",
        "dob": "1991-04-02",
        "gender": "FEMALE"
      }
    ],
    "activeSessionPackResponses": [],
    "allSessionPackResponses": []
  }
}

The data object is the same one described on verify and fetch records: associatedPatients, activeSessionPackResponses, allSessionPackResponses.

Use it for	Field
Choosing which family member is booking	`associatedPatients[].id` → `patientId`
Spending a pack	`activeSessionPackResponses[].id` → `patientPackageId`
Selling a pack	`allSessionPackResponses[].id` → `packageConfigId`

Common failures

Status	Cause
`400`	Neither a phone nor an email supplied.
`403`	`requiresVerification: true` — the OTP gate is closed or expired. Run the OTP pair again.

An empty result is not an error

A phone the clinic has never seen returns associatedPatients: [] with a 200. Create the record by booking with a patientPayload, or by editing details once it exists.

Search by phone

Query parameters

Try it

Request

Response

Common failures

On this page