> ## 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. # Get Referrals > Retrieve referrals from the Cobalt database for a specified date range. ## 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 ```bash theme={null} 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 ```json theme={null} { "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. ## OpenAPI ````yaml GET /referrals openapi: 3.0.0 info: title: Cobalt API version: 1.0.1 description: API for interacting with Cobalt's EHR integration services servers: - url: https://api.usecobalt.com/v1 security: - ClientCredentials: [] ClientSecret: [] AccessToken: [] paths: /referrals: get: summary: Get Referrals description: Retrieve referrals from the Cobalt database for a specified date range. parameters: - in: query name: start_date required: true schema: type: string format: date description: Start of the date range in ISO format (YYYY-MM-DD) - in: query name: end_date required: true schema: type: string format: date description: End of the date range in ISO format (YYYY-MM-DD) - in: query name: patient_mrn schema: type: string description: Filter by patient MRN - in: query name: status schema: type: string description: Filter by referral status - in: query name: priority schema: type: string enum: - routine - urgent - stat description: Filter by priority - in: query name: ehr_id schema: type: string description: Filter by the referral's EHR ID - in: query name: page schema: type: integer default: 1 description: 'Page number (default: 1)' - in: query name: page_size schema: type: integer default: 100 maximum: 100 description: 'Results per page, max 100 (default: 100)' - in: query name: sort schema: type: string description: >- Sort order — pass `created_at` for ascending, defaults to descending by referral date responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean referrals: type: array items: type: object properties: id: type: string description: Cobalt referral ID (UUID without dashes) ehr_id: type: string description: The referral ID as it appears in the EMR patient_ehr_id: type: string nullable: true description: The patient's EHR ID patient_mrn: type: string nullable: true description: Patient medical record number patient_first_name: type: string nullable: true description: Patient first name patient_last_name: type: string nullable: true description: Patient last name patient_dob: type: string nullable: true description: Patient date of birth from_provider_ehr_id: type: string nullable: true description: EHR ID of the referring provider from_provider_name: type: string nullable: true description: Name of the referring provider to_provider_ehr_id: type: string nullable: true description: EHR ID of the provider being referred to to_provider_name: type: string nullable: true description: Name of the provider being referred to priority: type: string nullable: true enum: - routine - urgent - stat description: Referral priority urgency: type: string nullable: true description: Urgency designation as recorded in the EMR reason: type: string nullable: true description: Reason for the referral diagnosis_codes: type: array items: type: string description: ICD-10 diagnosis codes associated with the referral document_ids: type: array items: type: string description: >- Cobalt IDs of attached documents (UUIDs without dashes) status: type: string nullable: true description: Current referral status referral_date: type: string nullable: true description: Date the referral was created (ISO 8601) last_activity_at: type: string nullable: true description: >- Timestamp of the most recent activity on the referral (ISO 8601) synced_at: type: string nullable: true description: Timestamp of the last sync from the EMR (ISO 8601) pagination: type: object properties: page: type: integer page_size: type: integer total_count: type: integer total_pages: type: integer components: securitySchemes: ClientCredentials: type: apiKey in: header name: client_id ClientSecret: type: apiKey in: header name: client_secret AccessToken: type: apiKey in: header name: access_token ````