Get Providers - Documentation

List 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>'

import requests

url = "https://api.usecobalt.com/v1/providers"

headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {client_id: '<api-key>', client_secret: '<api-key>', access_token: '<api-key>'}
};

fetch('https://api.usecobalt.com/v1/providers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/providers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/providers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.usecobalt.com/v1/providers")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/providers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "providers": [
    {
      "id": "<string>",
      "ehr_id": "<string>",
      "timezone": "<string>",
      "npi": "<string>",
      "specialty": "<string>",
      "credentials": "<string>",
      "name": "<string>",
      "status": "<string>",
      "hide_in_availability": true,
      "practice_locations": [
        {}
      ],
      "hours": [
        {}
      ],
      "complaint_types": [
        {}
      ]
    }
  ]
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

GET

providers

List 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>'

import requests

url = "https://api.usecobalt.com/v1/providers"

headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {client_id: '<api-key>', client_secret: '<api-key>', access_token: '<api-key>'}
};

fetch('https://api.usecobalt.com/v1/providers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/providers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/providers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.usecobalt.com/v1/providers")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/providers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "providers": [
    {
      "id": "<string>",
      "ehr_id": "<string>",
      "timezone": "<string>",
      "npi": "<string>",
      "specialty": "<string>",
      "credentials": "<string>",
      "name": "<string>",
      "status": "<string>",
      "hide_in_availability": true,
      "practice_locations": [
        {}
      ],
      "hours": [
        {}
      ],
      "complaint_types": [
        {}
      ]
    }
  ]
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<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'

To resolve a provider’s Cobalt id from an EHR-native identifier you already hold (for example when setting pcp_id on a patient), filter by ehr_id:

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' \
-G \
--data-urlencode "ehr_id=99999"

Example Response

{
    "success": true,
    "providers": [
        {
            "id": "abc123def4567890abcdef1234567890",
            "ehr_id": "99999",
            "timezone": "America/Phoenix",
            "npi": "425345345",
            "specialty": "Family Medicine",
            "credentials": "MD",
            "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

Query Parameters

ehr_id

string

Optional exact-match filter on the provider's EHR-native identifier; returns just that provider when supplied.

page

integer

default:1

Accepted for compatibility but ignored — every provider is returned.

Required range: x >= 1

page_size

integer

Accepted for compatibility but ignored — every provider is returned.

Required range: x >= 1

Response

Providers for the account

success

boolean

required

providers

object[]

required

Show child attributes

​Understanding Provider IDs

​Example Request

​Example Response

​Response Parameters

​Provider Fields

​Schedule Structure

Authorizations

Query Parameters

Response

Understanding Provider IDs

Example Request

Example Response

Response Parameters

Provider Fields

Schedule Structure