> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Patients

> Returns a list of patients with optional filtering and pagination.

### Example Request

```bash theme={null}
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

```json theme={null}
{
    "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
    }
}
```

<Note>
  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.
</Note>


## OpenAPI

````yaml GET /patients
openapi: 3.0.0
info:
  title: Cobalt API
  version: 1.0.1
  description: API for interacting with Cobalt's EHR integration services
servers:
  - url: https://api.usecobalt.com/v1
security:
  - ClientCredentials: []
    ClientSecret: []
    AccessToken: []
paths:
  /patients:
    get:
      summary: Get Patients
      description: Returns a list of patients with optional filtering and pagination.
      parameters:
        - in: query
          name: dob
          schema:
            type: string
            format: date
          description: 'Filter patients by date of birth (ISO 8601 format: YYYY-MM-DD)'
        - in: query
          name: first_name
          schema:
            type: string
          description: Filter patients by first name (case-insensitive, partial match)
        - in: query
          name: last_name
          schema:
            type: string
          description: Filter patients by last name (case-insensitive, partial match)
        - in: query
          name: mrn
          schema:
            type: string
          description: Filter patients by EHR MRN
        - in: query
          name: ehr_id
          schema:
            type: string
          description: Filter patients by EHR ID
        - in: query
          name: phone
          schema:
            type: string
          description: Filter patients by phone number (exact match)
        - in: query
          name: status
          schema:
            type: string
            enum:
              - active
              - inactive
              - all
            default: all
          description: >-
            Filter patients by status. Use 'active' for active patients,
            'inactive' for inactive patients, or 'all' for all patients.
            Defaults to 'all'
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: The page number for pagination
        - in: query
          name: page_size
          schema:
            type: integer
            default: 20
            maximum: 100
          description: The number of patients per page
        - in: query
          name: sort
          schema:
            type: string
            enum:
              - created_at
              - '-created_at'
            default: '-created_at'
          description: >-
            Sort order for results. Use 'created_at' for ascending (oldest
            first) or '-created_at' for descending (newest first). Defaults to
            '-created_at'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  patients:
                    type: array
                    items:
                      type: object
                      properties:
                        first_name:
                          type: string
                        last_name:
                          type: string
                        dob:
                          type: string
                          format: date
                        sex:
                          type: string
                        phone:
                          type: string
                        mrn:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                          description: Timestamp when the patient record was created
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        description: Current page number
                        example: 1
                      total_pages:
                        type: integer
                        description: Total number of pages
                        example: 2
                      total_count:
                        type: integer
                        description: Total number of items
                        example: 151
                      page_size:
                        type: integer
                        description: Number of items per page
                        example: 100
components:
  securitySchemes:
    ClientCredentials:
      type: apiKey
      in: header
      name: client_id
    ClientSecret:
      type: apiKey
      in: header
      name: client_secret
    AccessToken:
      type: apiKey
      in: header
      name: access_token

````