> ## 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.
# Update Referral
> Queues an update to an existing referral in the provider's EMR system.
Referrals are updated in the provider's EMR using the same asynchronous processing model as [creation](/api-reference/referrals/create). The update is not instantaneous.
Instead of leaving your PATCH request hanging until completion, we immediately return a success response if the request is properly formed. We then notify you via a webhook when the update has been applied in the EMR.
Updating referrals is currently supported for **eClinicalWorks**.
### Path Parameter
* **id** (string, required): The Cobalt referral ID (UUID) returned by [Create Referral](/api-reference/referrals/create) or [Get Referrals](/api-reference/referrals/get). The referral must already exist and have been created in the EMR.
### Request Parameters
Supply **one or more** of the following fields. Omitted fields are left unchanged in the EMR — this is a partial update.
* **priority** (string, optional): Referral priority — `routine`, `urgent`, or `stat`. Case-insensitive: `"Routine"`, `"URGENT"`, and `"stat"` are all accepted and normalized.
* **status** (string, optional): Referral status label — e.g. `"Open"`, `"Pending"`, `"Internal Review"`, `"Insurance Auth"`, `"Addressed"`. See [Status Values](#status-values) below.
* **reason** (string, optional): Reason for the referral.
* **notes** (string, optional): Free-text notes on the referral.
At least one updatable field must be present. An empty body returns a `400`.
### Status Values
The set of valid statuses — and their exact labels — is **specific to each EMR instance and organization**, not a fixed global list. When you PATCH a `status`, the value is resolved against that instance's live status list at processing time.
Because of this, you can pass a human-friendly, title-cased label with spaces (e.g. `"Internal Review"`) regardless of how the status is stored internally in the EMR. Matching is case- and spacing-insensitive.
If the supplied status does not match any status configured for the instance, the update fails and a `referral.failed` webhook is sent with `error_type: "ecw_validation_failure"`.
To discover which statuses an instance supports, inspect the `status` field returned by [Get Referrals](/api-reference/referrals/get) for existing referrals.
### Example Request
```bash theme={null}
curl -X PATCH https://api.usecobalt.com/v1/referrals/123e4567e89b12d3a456426614174000 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"priority": "urgent",
"status": "Internal Review",
"reason": "Updated cardiology consultation",
"notes": "Patient called to confirm availability."
}'
```
#### Update a Single Field
```bash theme={null}
curl -X PATCH https://api.usecobalt.com/v1/referrals/123e4567e89b12d3a456426614174000 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{ "status": "Addressed" }'
```
### Example Response
```json theme={null}
{
"success": true,
"message": "Referral queued for update. A webhook event will be sent upon completion.",
"referral_id": "123e4567e89b12d3a456426614174000",
"job_id": 12345
}
```
The response includes:
* **referral\_id**: Cobalt referral ID (UUID without dashes). Echoed back in the webhook payload so you can correlate the two.
* **job\_id**: Job execution identifier for tracking the async operation.
### Error Responses
#### Invalid Priority
```json theme={null}
{
"success": false,
"message": "Invalid priority. Must be one of: routine, urgent, stat (case-insensitive)."
}
```
#### Invalid Status
```json theme={null}
{
"success": false,
"message": "Invalid status. Must be a non-empty string."
}
```
#### No Updatable Fields
```json theme={null}
{
"success": false,
"message": "No updatable fields provided. Supply at least one of: priority, status, reason, notes."
}
```
#### Unexpected Fields
```json theme={null}
{
"success": false,
"message": "Unexpected fields in request body: foo. Updatable fields are: priority, status, reason, notes."
}
```
#### Invalid Referral ID
```json theme={null}
{
"success": false,
"message": "Invalid referral ID format. Must be a valid UUID."
}
```
#### Referral Not Yet in the EMR
```json theme={null}
{
"success": false,
"message": "Referral has not been created in the EMR yet and cannot be updated."
}
```
#### Referral Not Found
```json theme={null}
{
"success": false,
"message": "Referral not found."
}
```
### Webhook Notifications
When the update has finished processing, we send a webhook to your registered endpoint.
#### Success
```json theme={null}
{
"id": "",
"access_token_reference_id": "",
"object": "event",
"created": "2026-03-10T10:30:00.000Z",
"type": "referral.updated",
"job_id": "12345",
"data": {
"referral_id": "123e4567e89b12d3a456426614174000",
"ehr_id": "REF-00123",
"patient_mrn": "1234567",
"direction": "outgoing",
"updated_fields": ["priority", "status"]
}
}
```
`updated_fields` lists the fields that were applied in this update.
#### Failure
```json theme={null}
{
"id": "",
"access_token_reference_id": "",
"object": "event",
"created": "2026-03-10T10:35:00.000Z",
"type": "referral.failed",
"job_id": "12345",
"data": {
"referral_id": "123e4567e89b12d3a456426614174000",
"patient_mrn": "1234567",
"failure_reason": "The status \"Foo\" is not a valid status for this eCW instance.",
"error_type": "ecw_validation_failure"
}
}
```
`error_type` is only present for validation failures (e.g. an unrecognized status). Other failures omit it.
## OpenAPI
````yaml PATCH /referrals/{id}
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/{id}:
patch:
summary: Update Referral
description: >-
Queues an update to an existing referral in the provider's EMR system.
This is an asynchronous operation that returns immediately with a
referral_id and job_id, and sends a webhook notification upon
completion. Supply one or more of priority, status, reason, and notes;
omitted fields are left unchanged in the EMR.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: >-
Cobalt referral ID (UUID). The referral must already exist and have
been created in the EMR.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
priority:
type: string
enum:
- routine
- urgent
- stat
description: >-
Referral priority. Case-insensitive — "Routine", "URGENT",
and "stat" are all accepted and normalized.
status:
type: string
description: >-
Referral status label (e.g. "Open", "Pending", "Internal
Review", "Insurance Auth", "Addressed"). The set of valid
statuses is specific to each EMR instance/organization; the
value is resolved against the instance's live status list at
processing time. Case- and spacing-insensitive.
reason:
type: string
description: Reason for the referral.
notes:
type: string
description: Free-text notes on the referral.
responses:
'200':
description: Referral update queued successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example: >-
Referral queued for update. A webhook event will be sent
upon completion.
referral_id:
type: string
description: >-
Cobalt referral ID (UUID without dashes). Echoed back in
the webhook payload.
job_id:
type: integer
description: Job execution identifier for tracking the async operation.
'400':
description: >-
Bad request - validation error, or referral not yet created in the
EMR
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example: >-
Invalid priority. Must be one of: routine, urgent, stat
(case-insensitive).
'404':
description: Referral or user not found
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example: Referral not found.
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example: Error updating referral.
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
````