Get Referrals

​

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
• 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"],
      "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)
• 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.