> ## 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.

# List Telephone Encounters

> List telephone encounters synced from the EHR, filtered by date, assignee, status and more.

Returns telephone encounters synced from the EHR, newest first, with their status,
assignee and actions. Use an encounter's `id` to add an action with
[POST /telephone-encounters/actions](https://docs.usecobalt.com/api-reference/telephone-encounters/create-action.md).

## Query Parameters

* **start\_date** (string, required): Start of the date range (YYYY-MM-DD, inclusive). Matches the encounter date in the EHR.
* **end\_date** (string, required): End of the date range (YYYY-MM-DD, inclusive).
* **patient\_mrn** (string, optional): Patient MRN.
* **assigned\_to\_ehr\_id** (string, optional): Assignee's staff `ehr_id` from [GET /staff](https://docs.usecobalt.com/api-reference/staff/get.md).
* **assigned\_to\_name** (string, optional): Assignee name as shown in the EHR, e.g. `Smith, Alex`. Case- and space-insensitive.
* **created\_by** (string, optional): Name of the user who created the encounter, as shown in the EHR. Case- and space-insensitive.
* **locked** (string, optional): `true` for only addressed (locked) encounters, `false` for only open ones.
* **reason** (string, optional): Keyword in the reason, case-insensitive.
* **page** (integer, optional): Page number (default: 1).
* **page\_size** (integer, optional): Results per page, max 100 (default: 100).

## Example Request

```bash theme={null}
curl -G "https://api.usecobalt.com/v1/telephone-encounters" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  --data-urlencode "start_date=2026-10-05" \
  --data-urlencode "end_date=2026-10-07" \
  --data-urlencode "assigned_to_ehr_id=52685" \
  --data-urlencode "locked=false"
```

## Example Response

```json theme={null}
{
    "success": true,
    "telephone_encounters": [
        {
            "id": "7d2e4f1a9c3b4e8d8a6f2b1c0d9e8f7a",
            "ehr_id": "85479379",
            "patient_mrn": "12345",
            "patient_ehr_id": "3912234",
            "encounter_datetime": "2026-10-06T16:30:00.000Z",
            "reason": "Medication refill",
            "caller": "Doe, Jane (patient)",
            "message": "Patient requests a refill of their blood pressure medication.",
            "notes": null,
            "status": "open",
            "locked": false,
            "locked_at": null,
            "assigned_to_ehr_id": "52685",
            "assigned_to_name": "Smith, Alex",
            "created_by": "Doe, Jordan",
            "answered_by": "Doe, Jordan",
            "provider_ehr_id": "12241",
            "provider_name": "Lee, Morgan",
            "location_ehr_id": "25",
            "location_name": "Main Office",
            "is_high_priority": false,
            "has_attachment": false,
            "actions": [
                {
                    "by": "Doe, Jordan",
                    "at": "2026-10-06T16:42:00.000Z",
                    "text": "Sent refill request to provider."
                }
            ],
            "ehr_created_at": "2026-10-06T16:30:00.000Z",
            "ehr_updated_at": "2026-10-06T16:42:00.000Z",
            "created_at": "2026-10-06T16:45:10.000Z",
            "updated_at": "2026-10-06T16:45:10.000Z"
        }
    ],
    "pagination": {
        "page": 1,
        "page_size": 100,
        "total_count": 1,
        "total_pages": 1
    }
}
```

## Staying Up To Date

Subscribe to the `telephone_encounter.updated`
[sync event](https://docs.usecobalt.com/docs/webhooks/sync-events.md#telephone-encounter-events) to hear when an
encounter changes (addressed, reassigned, new actions or notes) without polling.

## Status Codes

* **200**: Telephone encounters returned.
* **400**: Missing or invalid dates, an invalid filter value, or an invalid `page` / `page_size`.


## OpenAPI

````yaml GET /telephone-encounters
openapi: 3.1.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
    description: Production
security:
  - ClientCredentials: []
    ClientSecret: []
    AccessToken: []
paths:
  /telephone-encounters:
    get:
      tags:
        - Telephone Encounters
      summary: List telephone encounters
      description: >-
        Lists telephone encounters stored from the EMR, newest first, with their
        status, assignee and actions.
      operationId: getTelephoneEncounters
      parameters:
        - name: start_date
          in: query
          description: >-
            Start of the date range (YYYY-MM-DD, inclusive), matched against the
            encounter date in the EHR.
          schema:
            type: string
            example: '2026-03-15'
          required: true
          x-supported-emrs:
            - eClinicalWorks
        - name: end_date
          in: query
          description: End of the date range (YYYY-MM-DD, inclusive).
          schema:
            type: string
            example: '2026-03-20'
          required: true
          x-supported-emrs:
            - eClinicalWorks
        - name: patient_mrn
          in: query
          description: Filter by patient Medical Record Number.
          schema:
            type: string
            example: '12345'
          required: false
          x-supported-emrs:
            - eClinicalWorks
        - name: assigned_to_ehr_id
          in: query
          description: 'Filter by assignee: a staff `ehr_id` from GET /v1/staff.'
          schema:
            type: string
            example: staff-123
          required: false
          x-supported-emrs:
            - eClinicalWorks
        - name: assigned_to_name
          in: query
          description: >-
            Filter by assignee name as shown in the EHR (e.g. "Smith, Jane"),
            case- and space-insensitive.
          schema:
            type: string
            example: Smith, Alex
          required: false
          x-supported-emrs:
            - eClinicalWorks
        - name: created_by
          in: query
          description: >-
            Filter by the user who created the encounter, as shown in the EHR
            (e.g. "Smith, Jane"), case- and space-insensitive.
          schema:
            type: string
            example: Smith, Alex
          required: false
          x-supported-emrs:
            - eClinicalWorks
        - name: locked
          in: query
          description: >-
            "true" returns only addressed (locked) encounters; "false" only open
            ones.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            example: 'false'
          required: false
          x-supported-emrs:
            - eClinicalWorks
        - name: reason
          in: query
          description: Filter by a keyword in the reason, case-insensitive.
          schema:
            type: string
            example: refill
          required: false
          x-supported-emrs:
            - eClinicalWorks
        - name: page
          in: query
          description: Page number (default 1).
          schema:
            type: string
            example: '1'
          required: false
          x-supported-emrs:
            - eClinicalWorks
        - name: page_size
          in: query
          description: Results per page (1-100, default 100).
          schema:
            type: string
            example: '100'
          required: false
          x-supported-emrs:
            - eClinicalWorks
      responses:
        '200':
          description: Telephone encounters for the account
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  telephone_encounters:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: >-
                            Cobalt telephone encounter ID (dashless UUID). Use
                            it to add an action with POST
                            /v1/telephone-encounters/actions.
                        ehr_id:
                          type: string
                          description: Encounter ID in the EHR.
                        patient_mrn:
                          type:
                            - string
                            - 'null'
                        patient_ehr_id:
                          type:
                            - string
                            - 'null'
                        encounter_datetime:
                          type:
                            - string
                            - 'null'
                          description: Encounter date and time in the EHR (ISO 8601).
                        reason:
                          type:
                            - string
                            - 'null'
                        caller:
                          type:
                            - string
                            - 'null'
                        message:
                          type:
                            - string
                            - 'null'
                        notes:
                          type:
                            - string
                            - 'null'
                        status:
                          type: string
                          enum:
                            - open
                            - addressed
                          description: '"addressed" once the encounter is locked in the EHR.'
                        locked:
                          type: boolean
                        locked_at:
                          type:
                            - string
                            - 'null'
                          description: >-
                            When the encounter was addressed (locked) in the
                            EHR, from its audit log.
                        assigned_to_ehr_id:
                          type:
                            - string
                            - 'null'
                          description: Assignee staff `ehr_id` (GET /v1/staff).
                        assigned_to_name:
                          type:
                            - string
                            - 'null'
                        created_by:
                          type:
                            - string
                            - 'null'
                          description: User who created the encounter in the EHR.
                        answered_by:
                          type:
                            - string
                            - 'null'
                        provider_ehr_id:
                          type:
                            - string
                            - 'null'
                        provider_name:
                          type:
                            - string
                            - 'null'
                        location_ehr_id:
                          type:
                            - string
                            - 'null'
                        location_name:
                          type:
                            - string
                            - 'null'
                        is_high_priority:
                          type: boolean
                        has_attachment:
                          type: boolean
                        actions:
                          type: array
                          items:
                            type: object
                            properties:
                              by:
                                type:
                                  - string
                                  - 'null'
                              at:
                                type:
                                  - string
                                  - 'null'
                                description: ISO 8601.
                              text:
                                type: string
                            required:
                              - by
                              - at
                              - text
                          description: Actions taken on the encounter, oldest first.
                        ehr_created_at:
                          type:
                            - string
                            - 'null'
                        ehr_updated_at:
                          type:
                            - string
                            - 'null'
                        created_at:
                          type: string
                        updated_at:
                          type: string
                      required:
                        - id
                        - ehr_id
                        - patient_mrn
                        - patient_ehr_id
                        - encounter_datetime
                        - reason
                        - caller
                        - message
                        - notes
                        - status
                        - locked
                        - locked_at
                        - assigned_to_ehr_id
                        - assigned_to_name
                        - created_by
                        - answered_by
                        - provider_ehr_id
                        - provider_name
                        - location_ehr_id
                        - location_name
                        - is_high_priority
                        - has_attachment
                        - actions
                        - ehr_created_at
                        - ehr_updated_at
                        - created_at
                        - updated_at
                    example:
                      - id: encounter-123
                        ehr_id: '85479379'
                        patient_mrn: '12345'
                        patient_ehr_id: '3912234'
                        encounter_datetime: '2026-06-15T21:30:00Z'
                        reason: Medication refill
                        caller: Jane Doe (patient)
                        message: >-
                          Patient requests a refill of their blood pressure
                          medication.
                        notes: null
                        status: addressed
                        locked: true
                        locked_at: '2026-06-15T21:30:00Z'
                        assigned_to_ehr_id: staff-123
                        assigned_to_name: Smith, Alex
                        created_by: Doe, Jordan
                        answered_by: Doe, Jordan
                        provider_ehr_id: provider-123
                        provider_name: Lee, Sam
                        location_ehr_id: location-1
                        location_name: Main Clinic
                        is_high_priority: false
                        has_attachment: false
                        actions:
                          - by: Smith, Alex
                            at: '2026-06-15T21:30:00Z'
                            text: >-
                              Called patient; left a message about their
                              results.
                        ehr_created_at: '2026-06-15T21:30:00Z'
                        ehr_updated_at: '2026-06-15T21:30:00Z'
                        created_at: '2026-06-15T21:30:00Z'
                        updated_at: '2026-06-15T21:30:00Z'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                        example: 1
                      page_size:
                        type: integer
                        example: 25
                      total_count:
                        type: integer
                        example: 1
                      total_pages:
                        type: integer
                        example: 1
                    required:
                      - page
                      - page_size
                      - total_count
                      - total_pages
                required:
                  - success
                  - telephone_encounters
                  - pagination
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
                example: false
              message:
                type: string
                example: Request could not be completed.
            required:
              - success
              - message
          example:
            success: false
            message: Bad request — missing or invalid parameters
    Unauthorized:
      description: Unauthorized — missing or invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
                example: false
              message:
                type: string
                example: Request could not be completed.
            required:
              - success
              - message
          example:
            success: false
            message: Unauthorized — missing or invalid credentials
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
                example: false
              message:
                type: string
                example: Request could not be completed.
            required:
              - success
              - message
          example:
            success: false
            message: Internal server error
  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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.