Skip to main content
Use this endpoint to search for patients within your tenant. You can filter by name (partial match), email, phone, gender, birth date, or active status. Results are paginated — use count and cursor to page through large result sets.

​
Request

GET https://api.clinikapi.com/v1/patients

​
Headers

​
x-api-key
string
required
Your ClinikAPI secret key (clk_live_* or clk_test_*).

​
Query Parameters

​
name
string
Filter by name using a partial, case-insensitive match against first name and last name.
​
email
string
Filter by email address (exact match).
​
phone
string
Filter by phone number (exact match).
​
gender
string
Filter by gender. One of: male, female, other, unknown.
​
birthDate
string
Filter by date of birth in YYYY-MM-DD format.
​
active
boolean
Filter by active status (true or false).
​
count
integer
Number of results per page. Default: 20. Maximum: 100.
​
cursor
string
Opaque pagination cursor from the previous response’s data.cursor field.

​
Response

Returns 200 OK with a paginated list of patients.
​
data.data
array
Array of patient objects matching the search criteria.
​
data.total
integer
Total number of patients matching the search, across all pages.
​
data.cursor
string
Cursor to pass in the next request to retrieve the following page. null when there are no more results.
​
data.hasMore
boolean
true if there are additional pages of results.
​
meta
object
Standard response metadata including requestId, timestamp, status, and rate-limit fields.

​
Examples

​
curl

curl "https://api.clinikapi.com/v1/patients?name=doe&gender=female&count=10" \
  -H "x-api-key: clk_live_abc123"

​
Paginating through results

# First page
curl "https://api.clinikapi.com/v1/patients?count=20" \
  -H "x-api-key: clk_live_abc123"

# Next page using cursor from previous response
curl "https://api.clinikapi.com/v1/patients?count=20&cursor=20" \
  -H "x-api-key: clk_live_abc123"

​
TypeScript SDK

import { ClinikAPI } from "@clinikapi/sdk";

const client = new ClinikAPI({ apiKey: "clk_live_abc123" });

const results = await client.patients.search({
  name: "doe",
  gender: "female",
  count: 10,
});

console.log(results.data.total);   // e.g. 42
console.log(results.data.hasMore); // true or false

for (const patient of results.data.data) {
  console.log(patient.id, patient.firstName, patient.lastName);
}