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

# Fetch Appointments

> Performs a live fetch of appointment data from the connected EMR system by date range, patient MRN, or provider.

<Note>
  This is a slow operation that fetches up-to-date appointment data directly from the EMR system. If the newest data is not critical, consider using the GET /appointments endpoint instead for faster results from cached data.
</Note>

## Search Modes

### Date Range (default)

Fetches appointments for a date range (max 7 days). Results are synced to the database and returned via webhook.

```json theme={null}
{
    "start_date": "2025-01-01",
    "end_date": "2025-01-07"
}
```

### MRN

Fetches all appointments for a specific patient by MRN, enriched with `created_at` and `created_by` timestamps.

```json theme={null}
{
    "search_by": "mrn",
    "mrn": "12345"
}
```

### Provider

Fetches appointments for one or more providers in a single EMR call. Results are synced to the database (scoped to the requested providers) and returned via webhook.

* `provider_ids`: required array of EMR provider IDs (max 10)
* 1 provider: `end_date` may be up to 5 days after `start_date`
* 2-10 providers: `start_date` must equal `end_date`

```json theme={null}
{
    "search_by": "provider",
    "start_date": "2025-01-01",
    "end_date": "2025-01-05",
    "provider_ids": ["prov_789", "prov_790"]
}
```

## Webhook Notifications

When the appointment fetch is complete, we will send a webhook to your registered endpoint.

### Date Range Webhook

```json theme={null}
{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "timestamp": "2023-10-28T11:00:00Z",
    "type": "appointment.live_fetch_completed",
    "action": "sync",
    "data": {
        "success": true,
        "appointment_count": 42,
        "start_date": "2025-01-01",
        "end_date": "2025-01-07",
        "appointments": [
            {
                "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
                "ehr_appointment_id": "12345678",
                "datetime": "2025-01-15T10:00:00-05:00",
                "duration": 30,
                "appointment_type": "Office Visit",
                "appointment_mode": null,
                "status": "CHK (Check Out)",
                "provider_ehr_id": "prov_789",
                "provider_name": "Smith, Jane",
                "provider_npi": "1234567890",
                "location": "Main Office",
                "patient_mrn": "85799",
                "patient_first_name": "Alex",
                "patient_last_name": "Doe",
                "patient_dob": "1985-04-12",
                "patient_gender": "M",
                "patient_phone": "555-555-5555",
                "patient_ehr_id": "PAT123",
                "cobalt_patient_id": "bbbbbbbbccccddddeeeeffffffffffff",
                "insurance": "Aetna",
                "insurances": null,
                "insurance_subscriber": null,
                "insurance_number": "W123456789",
                "insurance_group_number": null,
                "secondary_insurance": null,
                "secondary_insurance_number": null,
                "diagnoses": null
            }
        ]
    }
}
```

### MRN Webhook

```json theme={null}
{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "timestamp": "2023-10-28T11:00:00Z",
    "type": "appointment.live_fetch_completed",
    "action": "sync",
    "data": {
        "success": true,
        "search_by": "mrn",
        "mrn": "12345",
        "appointment_count": 7,
        "appointments": [
            {
                "ehr_appointment_id": "12345678",
                "datetime": "2025-04-07T13:00:00.000-07:00",
                "appointment_type": "OV (Office Visit)",
                "status": "PEN (Pending)",
                "provider_ehr_id": "prov_456",
                "provider_first_name": "Jane",
                "provider_last_name": "Smith",
                "reason": "Annual Checkup",
                "location": "Main Office",
                "locked": false,
                "created_at": "2025-02-20T07:52:02.000-08:00",
                "created_by": "Doe, John"
            }
        ]
    }
}
```

### Provider Webhook

Each appointment uses the same shape as the Date Range Webhook above.

```json theme={null}
{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cstuv",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "timestamp": "2023-10-28T11:00:00Z",
    "type": "appointment.live_fetch_completed",
    "action": "sync",
    "data": {
        "success": true,
        "search_by": "provider",
        "provider_ids": ["prov_789", "prov_790"],
        "start_date": "2025-01-01",
        "end_date": "2025-01-05",
        "appointment_count": 12,
        "appointments": [
            {
                "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
                "ehr_appointment_id": "12345678",
                "datetime": "2025-01-02T10:00:00-05:00",
                "duration": 30,
                "appointment_type": "Office Visit",
                "status": "CHK (Check Out)",
                "provider_ehr_id": "prov_789",
                "provider_name": "Smith, Jane",
                "provider_npi": "1234567890",
                "location": "Main Office",
                "patient_mrn": "85799",
                "patient_first_name": "Alex",
                "patient_last_name": "Doe",
                "patient_ehr_id": "PAT123",
                "cobalt_patient_id": "bbbbbbbbccccddddeeeeffffffffffff"
            }
        ]
    }
}
```


## OpenAPI

````yaml POST /appointments/fetch
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:
  /appointments/fetch:
    post:
      summary: Fetch Appointments
      description: >-
        Performs a live fetch of appointment data from the connected EMR system.
        Supports three search modes: by date range, by patient MRN, or by
        provider(s). This is an asynchronous operation that returns results via
        webhook.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                search_by:
                  type: string
                  enum:
                    - date_range
                    - mrn
                    - provider
                  default: date_range
                  description: >-
                    Search mode. Use `date_range` (default) to fetch by date
                    range, `mrn` to fetch by patient MRN with appointment audit
                    logs, or `provider` to fetch appointments scoped to one or
                    more EMR providers.
                start_date:
                  type: string
                  format: date
                  description: >-
                    Start date for the appointment range in ISO 8601 format
                    (YYYY-MM-DD). Required when `search_by` is `date_range` or
                    `provider`.
                end_date:
                  type: string
                  format: date
                  description: >-
                    End date for the appointment range in ISO 8601 format
                    (YYYY-MM-DD). For `date_range`, maximum range is 7 days. For
                    `provider`, the range may be up to 5 days after `start_date`
                    when exactly 1 provider is supplied; when 2-10 providers are
                    supplied, `end_date` must equal `start_date`. Required when
                    `search_by` is `date_range` or `provider`.
                mrn:
                  type: string
                  description: >-
                    Patient Medical Record Number. Required when `search_by` is
                    `mrn`.
                provider_ids:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 10
                  description: >-
                    Array of EMR provider IDs to fetch appointments for (max
                    10). Required when `search_by` is `provider`.
      responses:
        '202':
          description: Request accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  job_id:
                    type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
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

````