List patients

The List Patients endpoint is the primary way to sync patient rosters into your application, power search experiences, and back administrative dashboards. Results are cursor-paginated and include core demographics, external identifiers, and metadata you attach during create or update operations.

{
  "object": "list",
  "data": [{ "id": "pat_8Kx2mN1qRt", "object": "patient" }],
  "has_more": true
}

curl "https://api.vcaremd.com/v1/patients?limit=20" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY"

Overview

This endpoint supports read-only access and requires an API key with the patients:read scope. All responses are JSON and use UTC timestamps. Deleted patients are excluded by default unless you pass include_deleted=true (enterprise plans only).

Authentication

Include your secret key in the Authorization header on every request. Never call this endpoint from a browser or mobile app with a secret key — proxy through your backend instead.

curl "https://api.vcaremd.com/v1/patients?limit=20" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY"

Query parameters

Response

A successful request returns HTTP 200 with a JSON object containing a data array of patient objects and a has_more boolean indicating whether additional pages exist.

{
  "object": "list",
  "data": [
    {
      "id": "pat_8Kx2mN1qRt",
      "object": "patient",
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1985-03-12",
      "email": "jane.doe@example.com",
      "phone": "+14155552671",
      "created": 1720051200,
      "metadata": {
        "mrn": "MRN-10482"
      }
    }
  ],
  "has_more": true,
  "url": "/v1/patients"
}

Error responses

Code examples

import { Vcaremd } from "@vcaremd/api";

const client = new Vcaremd(process.env.VCAREMD_API_KEY);

for await (const patient of client.patients.list({ limit: 50 })) {
  console.log(patient.id, patient.email);
}

See Authentication for key management and rate limit headers on every response.

Use the limit parameter with strong pagination discipline — never assume a fixed page count when syncing large rosters.

Protected health information

Responses may include diagnoses, contact details, and insurance identifiers depending on your account configuration and the expand parameters you request.

Treat patient listings as PHI. Log patient IDs only in secure systems and never include full responses in client-side analytics.