Skip to main content
GET
/
patients
Get Patients
curl --request GET \
  --url https://api.usecobalt.com/v1/patients \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>'
{
  "success": true,
  "patients": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "dob": "2023-12-25",
      "sex": "<string>",
      "phone": "<string>",
      "mrn": "<string>",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 2,
    "total_count": 151,
    "page_size": 100
  }
}

​
Example Request

curl -X GET https://api.usecobalt.com/v1/patients \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-G \
--data-urlencode "first_name=John" \
--data-urlencode "last_name=Doe" \
--data-urlencode "page=2" \
--data-urlencode "page_size=30" \
--data-urlencode "sort=-created_at"

​
Example Response

{
    "success": true,
    "patients": [
        {
            "first_name": "John",
            "last_name": "Doe",
            "dob": "1980-05-15",
            "sex": "male",
            "phone": "555-123-4567",
            "mrn": "414421",
            "created_at": "2024-09-01T14:30:00Z"
        }
    ],
    "pagination": {
        "current_page": 2,
        "total_pages": 5,
        "total_count": 150,
        "page_size": 30
    }
}
All filter parameters are optional. If no filters are provided, the endpoint will return all patients, paginated according to the default values or specified page and page_size.

Authorizations

​
client_id
string
header
required
​
client_secret
string
header
required
​
access_token
string
header
required

Query Parameters

​
dob
string<date>

Filter patients by date of birth (ISO 8601 format: YYYY-MM-DD)

​
first_name
string

Filter patients by first name (case-insensitive, partial match)

​
last_name
string

Filter patients by last name (case-insensitive, partial match)

​
mrn
string

Filter patients by EHR MRN

​
ehr_id
string

Filter patients by EHR ID

​
phone
string

Filter patients by phone number (exact match)

​
status
enum<string>
default:all

Filter patients by status. Use 'active' for active patients, 'inactive' for inactive patients, or 'all' for all patients. Defaults to 'all'

Available options:
active,
inactive,
all
​
page
integer
default:1

The page number for pagination

​
page_size
integer
default:20

The number of patients per page

Required range: x <= 100
​
sort
enum<string>
default:-created_at

Sort order for results. Use 'created_at' for ascending (oldest first) or '-created_at' for descending (newest first). Defaults to '-created_at'

Available options:
created_at,
-created_at

Response

200 - application/json

Successful response

​
success
boolean
​
patients
object[]
​
pagination
object