List Patients¶

Retrieve a paginated list of patients in the system.

Endpoint¶

GET /v2/patients

Authentication¶

Requires a valid access token with patients:read or read scope.

Parameters¶

Query Parameters¶

Parameter	Type	Required	Default	Description
`page`	integer	No	1	Page number (1-based)
`per_page`	integer	No	25	Items per page (1-100)
`search`	string	No	-	Search term for name, email, or phone
`created_after`	string	No	-	ISO 8601 date filter
`created_before`	string	No	-	ISO 8601 date filter
`updated_after`	string	No	-	ISO 8601 date filter
`updated_before`	string	No	-	ISO 8601 date filter
`sort`	string	No	`created_at`	Sort field (`created_at`, `updated_at`, `last_name`, `first_name`)
`order`	string	No	`desc`	Sort order (`asc`, `desc`)
`status`	string	No	`active`	Patient status (`active`, `inactive`, `all`)
`fields`	string	No	-	Comma-separated field names to include
`expand`	string	No	-	Related resources to include (`medical_records`, `appointments`, `insurance`)

Request Examples¶

Basic RequestWith PaginationWith Search and FiltersWith Field SelectionWith Expansion

curl -X GET "https://api.emr-system.com/v2/patients" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

curl -X GET "https://api.emr-system.com/v2/patients?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

curl -X GET "https://api.emr-system.com/v2/patients?search=john&created_after=2024-01-01T00:00:00Z&sort=last_name&order=asc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

curl -X GET "https://api.emr-system.com/v2/patients?fields=id,first_name,last_name,email,phone" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

curl -X GET "https://api.emr-system.com/v2/patients?expand=medical_records,appointments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response¶

Success Response¶

Status Code: 200 OK

{
  "data": [
    {
      "id": "patient_7d2e1f8a9b3c4d5e",
      "first_name": "John",
      "last_name": "Doe",
      "middle_name": "Michael",
      "email": "john.doe@example.com",
      "phone": "+1-555-0123",
      "date_of_birth": "1990-05-15",
      "gender": "male",
      "status": "active",
      "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip_code": "12345",
        "country": "US"
      },
      "emergency_contact": {
        "name": "Jane Doe",
        "relationship": "spouse",
        "phone": "+1-555-0124"
      },
      "insurance": {
        "provider": "Blue Cross Blue Shield",
        "policy_number": "BC123456789",
        "group_number": "GRP001"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z"
    },
    {
      "id": "patient_9f4a2b6c8d7e1g3h",
      "first_name": "Sarah",
      "last_name": "Johnson",
      "middle_name": null,
      "email": "sarah.johnson@example.com",
      "phone": "+1-555-0456",
      "date_of_birth": "1985-03-22",
      "gender": "female",
      "status": "active",
      "address": {
        "street": "456 Oak Ave",
        "city": "Springfield",
        "state": "IL",
        "zip_code": "62701",
        "country": "US"
      },
      "emergency_contact": {
        "name": "Robert Johnson",
        "relationship": "father",
        "phone": "+1-555-0457"
      },
      "insurance": {
        "provider": "Aetna",
        "policy_number": "AET987654321",
        "group_number": "GRP002"
      },
      "created_at": "2024-02-01T09:15:00Z",
      "updated_at": "2024-02-10T16:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 10,
    "total_count": 250,
    "per_page": 25,
    "has_next": true,
    "has_previous": false,
    "next_page": 2,
    "previous_page": null
  },
  "meta": {
    "timestamp": "2024-12-07T14:25:00Z",
    "request_id": "req_abc123def456",
    "api_version": "2.1.0"
  }
}

Response with Expansion¶

When using expand=medical_records,appointments:

{
  "data": [
    {
      "id": "patient_7d2e1f8a9b3c4d5e",
      "first_name": "John",
      "last_name": "Doe",
      // ... other patient fields
      "medical_records": [
        {
          "id": "record_1a2b3c4d",
          "date": "2024-01-15",
          "diagnosis": "Hypertension",
          "provider_id": "provider_123"
        }
      ],
      "appointments": [
        {
          "id": "appointment_5e6f7g8h",
          "date": "2024-01-25T10:00:00Z",
          "status": "scheduled",
          "provider_id": "provider_456"
        }
      ]
    }
  ],
  // ... pagination and meta
}

Response Fields¶

Field	Type	Description
`id`	string	Unique patient identifier
`first_name`	string	Patient's first name
`last_name`	string	Patient's last name
`middle_name`	string\|null	Patient's middle name
`email`	string	Patient's email address
`phone`	string	Patient's phone number
`date_of_birth`	string	Date of birth (ISO 8601 date)
`gender`	string	Gender (`male`, `female`, `other`, `unknown`)
`status`	string	Patient status (`active`, `inactive`)
`address`	object	Patient's address information
`emergency_contact`	object	Emergency contact information
`insurance`	object	Insurance information
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Address Object¶

Field	Type	Description
`street`	string	Street address
`city`	string	City name
`state`	string	State/province code
`zip_code`	string	Postal/ZIP code
`country`	string	Country code (ISO 3166-1 alpha-2)

Emergency Contact Object¶

Field	Type	Description
`name`	string	Contact person's name
`relationship`	string	Relationship to patient
`phone`	string	Contact phone number

Insurance Object¶

Field	Type	Description
`provider`	string	Insurance provider name
`policy_number`	string	Policy number
`group_number`	string	Group number

Error Responses¶

Invalid Parameters¶

Status Code: 400 Bad Request

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid parameter value",
    "details": {
      "parameter": "per_page",
      "value": "150",
      "reason": "Must be between 1 and 100"
    }
  },
  "meta": {
    "timestamp": "2024-12-07T14:25:00Z",
    "request_id": "req_error123"
  }
}

Unauthorized¶

Status Code: 401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "details": {
      "reason": "Invalid or expired access token"
    }
  },
  "meta": {
    "timestamp": "2024-12-07T14:25:00Z",
    "request_id": "req_error456"
  }
}

Insufficient Permissions¶

Status Code: 403 Forbidden

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Insufficient permissions to access this resource",
    "details": {
      "required_scope": "patients:read",
      "current_scopes": ["appointments:read"]
    }
  },
  "meta": {
    "timestamp": "2024-12-07T14:25:00Z",
    "request_id": "req_error789"
  }
}

Rate Limits¶

This endpoint is subject to the standard rate limits:

Free Plan: 60 requests per minute
Professional Plan: 300 requests per minute
Enterprise Plan: 1,000 requests per minute

Code Examples¶

JavaScriptPythonPHPcURL

async function getPatients(page = 1, searchTerm = '') {
  const params = new URLSearchParams({
    page: page.toString(),
    per_page: '25'
  });

  if (searchTerm) {
    params.append('search', searchTerm);
  }

  const response = await fetch(`https://api.emr-system.com/v2/patients?${params}`, {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

// Usage
try {
  const patients = await getPatients(1, 'john');
  console.log(`Found ${patients.pagination.total_count} patients`);
  patients.data.forEach(patient => {
    console.log(`${patient.first_name} ${patient.last_name} - ${patient.email}`);
  });
} catch (error) {
  console.error('Error fetching patients:', error);
}

import requests
from typing import Optional, Dict, Any

def get_patients(
    access_token: str,
    page: int = 1,
    per_page: int = 25,
    search: Optional[str] = None,
    sort: str = 'created_at',
    order: str = 'desc'
) -> Dict[str, Any]:
    """Fetch patients from the EMR API."""

    params = {
        'page': page,
        'per_page': per_page,
        'sort': sort,
        'order': order
    }

    if search:
        params['search'] = search

    headers = {
        'Authorization': f'Bearer {access_token}',
        'Accept': 'application/json'
    }

    response = requests.get(
        'https://api.emr-system.com/v2/patients',
        params=params,
        headers=headers
    )

    response.raise_for_status()
    return response.json()

# Usage
try:
    result = get_patients(
        access_token='your_access_token',
        search='john',
        sort='last_name',
        order='asc'
    )

    print(f"Found {result['pagination']['total_count']} patients")
    for patient in result['data']:
        print(f"{patient['first_name']} {patient['last_name']} - {patient['email']}")

except requests.exceptions.RequestException as e:
    print(f"Error fetching patients: {e}")

<?php

function getPatients($accessToken, $page = 1, $search = null) {
    $baseUrl = 'https://api.emr-system.com/v2/patients';

    $params = [
        'page' => $page,
        'per_page' => 25
    ];

    if ($search) {
        $params['search'] = $search;
    }

    $url = $baseUrl . '?' . http_build_query($params);

    $headers = [
        'Authorization: Bearer ' . $accessToken,
        'Accept: application/json'
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("HTTP error: " . $httpCode);
    }

    return json_decode($response, true);
}

// Usage
try {
    $patients = getPatients('your_access_token', 1, 'john');
    echo "Found " . $patients['pagination']['total_count'] . " patients\n";

    foreach ($patients['data'] as $patient) {
        echo $patient['first_name'] . ' ' . $patient['last_name'] . ' - ' . $patient['email'] . "\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

#!/bin/bash

# Set your access token
ACCESS_TOKEN="your_access_token_here"

# Basic request
curl -X GET "https://api.emr-system.com/v2/patients" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json" \
  | jq '.'

# With search and pagination
curl -X GET "https://api.emr-system.com/v2/patients?search=john&page=1&per_page=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json" \
  | jq '.data[] | {id, first_name, last_name, email}'

# With sorting
curl -X GET "https://api.emr-system.com/v2/patients?sort=last_name&order=asc" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json" \
  | jq '.data[] | .last_name' | sort

Get Patient - Retrieve a specific patient
Create Patient - Create a new patient
Update Patient - Update patient information
Delete Patient - Remove a patient