Get Referrals - Cobalt

List 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": "2023-12-25",
      "from_provider_ehr_id": "<string>",
      "from_provider_name": "<string>",
      "to_provider_ehr_id": "<string>",
      "to_provider_name": "<string>",
      "priority": "<string>",
      "urgency": "<string>",
      "reason": "<string>",
      "prior_authorization_code": "<string>",
      "specialty": "<string>",
      "to_facility_name": "<string>",
      "diagnosis_codes": [
        "<string>"
      ],
      "document_ids": [
        "<string>"
      ],
      "direction": "<string>",
      "receiving_line": "<string>",
      "referral_source": "<string>",
      "patient_email": "<string>",
      "patient_phone": "<string>",
      "insurance_name": "<string>",
      "insurance_member_id": "<string>",
      "insurance_group_number": "<string>",
      "insurance_policy_status": "<string>",
      "insurance_effective_date": "<string>",
      "target_admission_date": "2023-12-25",
      "status": "<string>",
      "referral_date": "<string>",
      "last_activity_at": "<string>",
      "synced_at": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "page_size": 123,
    "total_count": 123,
    "total_pages": 123
  }
}

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

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

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

GET

referrals

List 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": "2023-12-25",
      "from_provider_ehr_id": "<string>",
      "from_provider_name": "<string>",
      "to_provider_ehr_id": "<string>",
      "to_provider_name": "<string>",
      "priority": "<string>",
      "urgency": "<string>",
      "reason": "<string>",
      "prior_authorization_code": "<string>",
      "specialty": "<string>",
      "to_facility_name": "<string>",
      "diagnosis_codes": [
        "<string>"
      ],
      "document_ids": [
        "<string>"
      ],
      "direction": "<string>",
      "receiving_line": "<string>",
      "referral_source": "<string>",
      "patient_email": "<string>",
      "patient_phone": "<string>",
      "insurance_name": "<string>",
      "insurance_member_id": "<string>",
      "insurance_group_number": "<string>",
      "insurance_policy_status": "<string>",
      "insurance_effective_date": "<string>",
      "target_admission_date": "2023-12-25",
      "status": "<string>",
      "referral_date": "<string>",
      "last_activity_at": "<string>",
      "synced_at": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "page_size": 123,
    "total_count": 123,
    "total_pages": 123
  }
}

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

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

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

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.
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",
      "prior_authorization_code": "AUTH-12345",
      "specialty": "Cardiology",
      "to_facility_name": "Example Regional Hospital",
      "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
prior_authorization_code (string, nullable): Prior authorization code recorded on the referral
specialty (string, nullable): Referral specialty
to_facility_name (string, nullable): Name of the facility the referral is directed to
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).
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

required

Start of the referral date range (ISO 8601, YYYY-MM-DD).

Example:

"2026-03-15"

end_date

string

required

End of the referral date range (ISO 8601, YYYY-MM-DD).

Example:

"2026-03-20"

patient_mrn

string

Filter by patient Medical Record Number.

Example:

"12345"

status

string

Filter by referral status.

Example:

"Sent"

priority

string

Filter by referral priority.

Example:

"routine"

direction

string

Filter by referral direction (incoming, outgoing).

Example:

"outgoing"

ehr_id

string

Filter by the referral’s EHR ID.

receiving_line

string

Filter by the receiving line.

page

integer

default:1

Page number.

Required range: x >= 1

page_size

integer

default:100

Items per page (max 100).

Required range: 1 <= x <= 100

sort

enum<string>

Sort order. "created_at" sorts oldest-first; the default is newest-first.

Available options:

created_at

Response

Referrals for the account

success

boolean

required

referrals

object[]

required

Show child attributes

pagination

object

required

Show child attributes

​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