Skip to main content
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>'
{
  "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>"
      ],
      "status": "<string>",
      "referral_date": "<string>",
      "last_activity_at": "<string>",
      "synced_at": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "page_size": 123,
    "total_count": 123,
    "total_pages": 123
  }
}

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.

​
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
  • 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",
      "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
  • 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
​
ehr_id
string

Filter by the referral's EHR ID

​
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[]
​
pagination
object