Get Referrals

curl --request GET \
  --url https://api.usecobalt.com/v1/referrals \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>'

import requests

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

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/referrals', 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/referrals",
  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/referrals"

	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/referrals")
  .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/referrals")

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,
  "referrals": [
    {
      "id": "<string>",
      "ehr_id": "<string>",
      "patient_ehr_id": "<string>",
      "patient_mrn": "<string>",
      "patient_first_name": "<string>",
      "patient_last_name": "<string>",
      "patient_dob": "<string>",
      "from_provider_ehr_id": "<string>",
      "from_provider_name": "<string>",
      "to_provider_ehr_id": "<string>",
      "to_provider_name": "<string>",
      "urgency": "<string>",
      "reason": "<string>",
      "diagnosis_codes": [
        "<string>"
      ],
      "document_ids": [
        "<string>"
      ],
      "direction": "<string>",
      "receiving_line": "<string>",
      "status": "<string>",
      "referral_date": "<string>",
      "last_activity_at": "<string>",
      "synced_at": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "page_size": 123,
    "total_count": 123,
    "total_pages": 123
  }
}

GET

referrals

Get Referrals

curl --request GET \
  --url https://api.usecobalt.com/v1/referrals \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>'

import requests

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

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/referrals', 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/referrals",
  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/referrals"

	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/referrals")
  .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/referrals")

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,
  "referrals": [
    {
      "id": "<string>",
      "ehr_id": "<string>",
      "patient_ehr_id": "<string>",
      "patient_mrn": "<string>",
      "patient_first_name": "<string>",
      "patient_last_name": "<string>",
      "patient_dob": "<string>",
      "from_provider_ehr_id": "<string>",
      "from_provider_name": "<string>",
      "to_provider_ehr_id": "<string>",
      "to_provider_name": "<string>",
      "urgency": "<string>",
      "reason": "<string>",
      "diagnosis_codes": [
        "<string>"
      ],
      "document_ids": [
        "<string>"
      ],
      "direction": "<string>",
      "receiving_line": "<string>",
      "status": "<string>",
      "referral_date": "<string>",
      "last_activity_at": "<string>",
      "synced_at": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "page_size": 123,
    "total_count": 123,
    "total_pages": 123
  }
}

Query Parameters

start_date (string, required): Start of the date range in ISO format (YYYY-MM-DD)
end_date (string, required): End of the date range in ISO format (YYYY-MM-DD)
patient_mrn (string, optional): Filter by patient MRN
status (string, optional): Filter by referral status
priority (string, optional): Filter by priority — routine, urgent, or stat
direction (string, optional): Filter by referral direction — incoming or outgoing
ehr_id (string, optional): Filter by the referral’s EMR ID
receiving_line (string, optional): Filter by the receiving line — the fax number that received the document. Accepts any format; the value is canonicalized to E.164 before matching. Currently populated for ModMed EMA referrals only.
page (integer, optional): Page number (default: 1)
page_size (integer, optional): Results per page, max 100 (default: 100)
sort (string, optional): Sort order — pass created_at for ascending, defaults to descending by referral date

Example Request

curl -X GET "https://api.usecobalt.com/v1/referrals?start_date=2026-03-01&end_date=2026-03-31" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token"

Example Response

{
  "success": true,
  "referrals": [
    {
      "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "ehr_id": "REF-00123",
      "patient_ehr_id": "PAT-456",
      "patient_mrn": "1234567",
      "patient_first_name": "Jane",
      "patient_last_name": "Smith",
      "patient_dob": "1985-03-15",
      "from_provider_ehr_id": "PROV-001",
      "from_provider_name": "Dr. John Doe",
      "to_provider_ehr_id": "PROV-002",
      "to_provider_name": "Dr. Sarah Lee",
      "priority": "urgent",
      "urgency": "urgent",
      "reason": "Cardiology consultation",
      "diagnosis_codes": ["I10", "Z87.39"],
      "document_ids": ["b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5"],
      "direction": "incoming",
      "receiving_line": "+12345678901",
      "status": "pending",
      "referral_date": "2026-03-10T00:00:00.000Z",
      "last_activity_at": "2026-03-11T14:30:00.000Z",
      "synced_at": "2026-03-11T14:35:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 100,
    "total_count": 1,
    "total_pages": 1
  }
}

Response Fields

Top-Level Fields

success (boolean): Whether the request was successful
referrals (array): Array of referral objects
pagination (object): Pagination metadata

Referral Object

id (string): Cobalt referral ID (UUID without dashes)
ehr_id (string): The referral ID as it appears in the EMR
patient_ehr_id (string, nullable): The patient’s EMR ID
patient_mrn (string, nullable): Patient medical record number
patient_first_name (string, nullable): Patient first name
patient_last_name (string, nullable): Patient last name
patient_dob (string, nullable): Patient date of birth
from_provider_ehr_id (string, nullable): EMR ID of the referring provider
from_provider_name (string, nullable): Name of the referring provider
to_provider_ehr_id (string, nullable): EMR ID of the provider being referred to
to_provider_name (string, nullable): Name of the provider being referred to
priority (string, nullable): Referral priority — routine, urgent, or stat
urgency (string, nullable): Urgency designation as recorded in the EMR
reason (string, nullable): Reason for the referral
diagnosis_codes (array): ICD-10 diagnosis codes associated with the referral
document_ids (array): Cobalt IDs of attached documents (UUIDs without dashes)
direction (string, nullable): Referral direction — incoming or outgoing
receiving_line (string, nullable): The receiving line — the fax number that received the document — in E.164 format (e.g. +12345678901). Currently populated for ModMed EMA referrals only; null otherwise.
status (string, nullable): Current referral status
referral_date (string, nullable): Date the referral was created (ISO 8601)
last_activity_at (string, nullable): Timestamp of the most recent activity on the referral (ISO 8601)
synced_at (string, nullable): Timestamp of the last sync from the EMR (ISO 8601)

Notes

This endpoint returns referrals from the Cobalt database. Data is updated during scheduled syncs.

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Query Parameters

start_date

string<date>

required

Start of the date range in ISO format (YYYY-MM-DD)

end_date

string<date>

required

End of the date range in ISO format (YYYY-MM-DD)

patient_mrn

string

Filter by patient MRN

status

string

Filter by referral status

priority

enum<string>

Filter by priority

Available options:

routine,

urgent,

stat

direction

enum<string>

Filter by referral direction

Available options:

incoming,

outgoing

ehr_id

string

Filter by the referral's EHR ID

receiving_line

string

Filter by the receiving line (the fax number that received the document), in E.164 format (e.g. +12345678901). Accepts any format; the value is canonicalized before matching. Currently populated for ModMed EMA referrals only.

page

integer

default:1

Page number (default: 1)

page_size

integer

default:100

Results per page, max 100 (default: 100)

Required range: x <= 100

sort

string

Sort order — pass created_at for ascending, defaults to descending by referral date

Response

200 - application/json

Successful response

success

boolean

referrals

object[]

Show child attributes

pagination

object

Show child attributes

API Documentation

Account

Appointments

Availability

Claims

Documents

Eligibility

Fee Schedules

Insurance

Link

Locations

Messages

Notes

Orders

Org Settings

Patient Notes

Patients

Payments

Pharmacies

Providers

Recalls

Referrals

Referring Providers

Settings

Tasks

Telephone Encounters

Visit Statuses

Visit Types

Webhooks

Get Referrals

Query Parameters

Example Request

Example Response

Response Fields

Top-Level Fields

Referral Object

Notes

Authorizations

Query Parameters

Response

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Top-Level Fields

​Referral Object

​Notes

Authorizations

Query Parameters

Response

Query Parameters

Example Request

Example Response

Response Fields

Top-Level Fields

Referral Object

Notes