Skip to main content
GET
/
providers
Get Providers
curl --request GET \
  --url https://api.usecobalt.com/v1/providers \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>'
{
  "success": true,
  "providers": [
    {
      "id": "<string>",
      "ehr_id": "<string>",
      "name": "<string>",
      "timezone": "<string>",
      "status": "active",
      "hours": [
        {
          "day": "<string>",
          "shifts": [
            {
              "start": "<string>",
              "end": "<string>",
              "facility_id": "<string>",
              "recurrence": {
                "rec_start_date": "<string>",
                "recur_interval_type": "<string>",
                "recur_interval_amount": "<string>",
                "recur_interval_description": "<string>"
              },
              "set_end_date": "<string>",
              "facility_name": "<string>",
              "set_start_date": "<string>",
              "set_description": "<string>",
              "visit_type_rules": [
                {
                  "end_time": "<string>",
                  "start_time": "<string>",
                  "total_visits": 123,
                  "visit_type_id": "<string>",
                  "visit_type_desc": "<string>"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

​
Understanding Provider IDs

Each provider has two identifiers:
  • id: Cobalt’s internal identifier (32-character UUID without hyphens)
    • Use when updating provider settings like status or hours
    • Operations: PATCH /v1/providers/{id}
  • ehr_id: Your EMR system’s provider identifier
    • Use when creating appointments or other EMR operations
    • Operations: POST /v1/appointments (provider field)
Why two IDs? Different operations work in different contexts. Provider management (updating status, hours) modifies Cobalt’s cached configuration, while appointment creation communicates directly with your EMR. Cobalt uses its own IDs to manage provider settings independently of EMR constraints, then maps to EMR IDs when interacting with your EMR system.
Quick Reference:
  • Updating provider settings → Use id
  • Creating appointments → Use ehr_id

​
Example Request

curl -X GET https://api.usecobalt.com/v1/providers \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH'

​
Example Response

{
    "success": true,
    "providers": [
        {
            "id": "abc123def4567890abcdef1234567890",
            "ehr_id": "99999",
            "timezone": "America/Phoenix",
            "npi": "425345345",
            "name": "Doe, John",
            "status": "active",
            "hide_in_availability": false,
            "hours": [
                {
                    "day": "Monday",
                    "shifts": [
                        {
                            "end": "T12:00:00",
                            "start": "T08:00:00",
                            "set_start_date": "2024-11-20",
                            "set_end_date": "2025-11-20",
                            "facility_id": "2",
                            "facility_name": "Acme Clinic",
                            "recurrence": {
                                "rec_start_date": "2024-11-20",
                                "recur_interval_type": "weeks",
                                "recur_interval_amount": 1,
                                "recur_interval_description": "Every 1 week."
                            },
                            "visit_type_rules": [
                                {
                                    "end_time": "13:45:00",
                                    "start_time": "13:00:00",
                                    "total_visits": 1,
                                    "visit_type_id": "NP",
                                    "visit_type_desc": "New Patient"
                                },
                            ]
                        },
                        {
                            "end": "T16:30:00",
                            "start": "T13:00:00"
                        }
                    ]
                },
            ]
        }
    ]
}

​
Response Parameters

​
Provider Fields

  • id: Cobalt’s internal provider identifier (used for updating provider settings)
  • ehr_id: EMR system’s provider identifier (used for creating appointments)
  • timezone: Provider’s timezone
  • npi: National Provider Identifier
  • name: Provider’s name
  • status: Provider status (active or inactive)
    • active: Provider’s schedule will be synced from the EMR
    • inactive: Provider’s schedule will not be synced
  • hide_in_availability: Whether provider is hidden from availability results (boolean, defaults to false)
    • false: Provider appears in /v1/availability endpoint results (default behavior)
    • true: Provider’s schedule is synced but hidden from availability results
    • Use case: Set to true when you want to continue syncing a provider’s schedule (for reporting/historical purposes) but don’t want them to appear as available for new appointments
    • Important: For a provider to appear in availability, BOTH conditions must be true:
      1. active must be true (schedule is being synced)
      2. hide_in_availability must be false (not explicitly hidden)

​
Schedule Structure

  • Day: Specifies which day of the week the schedule applies to
  • Shifts: Array of work periods with:
    • Start/end times using 24-hour format. Times are in the clinic’s eCW instance’s timezone.
    • Facility information (name and ID)
    • Date range when the schedule is active (start date and optional end date. If there is no end date then the shift is active indefinitely).
  • Visit Type Rules (optional):
    • Pre-allocated slots for specific appointment types
    • Each slot has its own start/end times
    • Includes description and total allowed appointments
  • Recurrence (optional):
    • Defines repeating patterns (e.g., “every 2 weeks”)
    • Contains start date and interval information
    • Allows for schedules that don’t occur every week

Authorizations

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

Response

200 - application/json

Successful response

​
success
boolean
​
providers
object[]