Skip to main content
PATCH
Update Referral
Referrals are updated in the provider’s EMR using the same asynchronous processing model as creation. 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 or Get Referrals. 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 below.
  • reason (string, optional): Reason for the referral.
  • notes (string, optional): Free-text notes on the referral.
  • prior_authorization_code (string, optional): Prior authorization code to write on the referral.
  • specialty (string, optional): Referral specialty name — e.g. "Cardiology". See Specialty below.
  • location_id (string, optional): EMR location ID of the facility the referral is directed to. See To Facility below.
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 for existing referrals.

Specialty

Pass specialty as the human-friendly specialty name (e.g. "Cardiology", "Sport Medicine"). The name is resolved against the EMR instance’s live specialty list at processing time, so the exact set of valid names is instance/organization specific. If the supplied specialty does not match any specialty configured for the instance, the update fails and a referral.failed webhook is sent with error_type: "ecw_validation_failure".

To Facility

Pass location_id as the EMR location ID of the facility the referral is directed to. It is validated synchronously against the account’s synced locations — an unknown location returns a 404 and no update is queued. Resolve location IDs with GET /v1/locations; use the location’s emr_id value.

Example Request

Update a Single Field

Example Response

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

Invalid Status

No Updatable Fields

Unexpected Fields

Unknown Location

Returned when location_id does not match a synced location for the account. Validated synchronously, so no update is queued.

Invalid Referral ID

Referral Not Yet in the EMR

Referral Not Found

Webhook Notifications

When the update has finished processing, we send a webhook to your registered endpoint.

Success

updated_fields lists the fields that were applied in this update.

Failure

error_type is only present for validation failures (e.g. an unrecognized status or specialty). Other failures omit it.

Authorizations

client_id
string
header
required
client_secret
string
header
required
access_token
string
header
required

Path Parameters

id
string
required

Cobalt referral ID (UUID). The referral must already exist and have been created in the EMR.

Body

application/json
priority
enum<string>

Referral priority. Case-insensitive — "Routine", "URGENT", and "stat" are all accepted and normalized.

Available options:
routine,
urgent,
stat
status
string

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
string

Reason for the referral.

notes
string

Free-text notes on the referral.

prior_authorization_code
string

Prior authorization code to write on the referral.

specialty
string

Referral specialty name (e.g. "Cardiology"). Resolved against the EMR instance's live specialty list at processing time; an unrecognized specialty fails with a referral.failed webhook.

location_id
string

EMR location ID of the facility the referral is directed to. Validated against the account's synced locations; an unknown location returns a 404. Resolve IDs with GET /v1/locations.

Response

Referral update queued successfully

success
boolean
message
string
Example:

"Referral queued for update. A webhook event will be sent upon completion."

referral_id
string

Cobalt referral ID (UUID without dashes). Echoed back in the webhook payload.

job_id
integer

Job execution identifier for tracking the async operation.