Update Referral
Queues an update to an existing referral in the provider’s EMR system.
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, orstat. 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.
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 astatus, 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".
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 a404 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
- 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 whenlocation_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
Path Parameters
Cobalt referral ID (UUID). The referral must already exist and have been created in the EMR.
Body
Referral priority. Case-insensitive — "Routine", "URGENT", and "stat" are all accepted and normalized.
routine, urgent, stat 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 for the referral.
Free-text notes on the referral.
Prior authorization code to write on the referral.
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.
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