Update Referral

Update a referral

curl --request PATCH \
  --url https://api.usecobalt.com/v1/referrals/{id} \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "priority": "routine",
  "status": "Sent",
  "reason": "Specialist consultation",
  "notes": "Please schedule the patient within two weeks.",
  "prior_authorization_code": "AUTH-12345",
  "specialty": "Cardiology",
  "location_id": "location-1",
  "start_date": "2026-09-01",
  "end_date": "2027-09-14",
  "visits_allowed": 14,
  "assigned_to_id": "STAFF-123",
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/referrals/{id}"

payload = {
    "priority": "routine",
    "status": "Sent",
    "reason": "Specialist consultation",
    "notes": "Please schedule the patient within two weeks.",
    "prior_authorization_code": "AUTH-12345",
    "specialty": "Cardiology",
    "location_id": "location-1",
    "start_date": "2026-09-01",
    "end_date": "2027-09-14",
    "visits_allowed": 14,
    "assigned_to_id": "STAFF-123",
    "callback_urls": ["https://example.com/webhooks/cobalt"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    priority: 'routine',
    status: 'Sent',
    reason: 'Specialist consultation',
    notes: 'Please schedule the patient within two weeks.',
    prior_authorization_code: 'AUTH-12345',
    specialty: 'Cardiology',
    location_id: 'location-1',
    start_date: '2026-09-01',
    end_date: '2027-09-14',
    visits_allowed: 14,
    assigned_to_id: 'STAFF-123',
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/referrals/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/referrals/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'priority' => 'routine',
    'status' => 'Sent',
    'reason' => 'Specialist consultation',
    'notes' => 'Please schedule the patient within two weeks.',
    'prior_authorization_code' => 'AUTH-12345',
    'specialty' => 'Cardiology',
    'location_id' => 'location-1',
    'start_date' => '2026-09-01',
    'end_date' => '2027-09-14',
    'visits_allowed' => 14,
    'assigned_to_id' => 'STAFF-123',
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/referrals/{id}"

	payload := strings.NewReader("{\n  \"priority\": \"routine\",\n  \"status\": \"Sent\",\n  \"reason\": \"Specialist consultation\",\n  \"notes\": \"Please schedule the patient within two weeks.\",\n  \"prior_authorization_code\": \"AUTH-12345\",\n  \"specialty\": \"Cardiology\",\n  \"location_id\": \"location-1\",\n  \"start_date\": \"2026-09-01\",\n  \"end_date\": \"2027-09-14\",\n  \"visits_allowed\": 14,\n  \"assigned_to_id\": \"STAFF-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.usecobalt.com/v1/referrals/{id}")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"priority\": \"routine\",\n  \"status\": \"Sent\",\n  \"reason\": \"Specialist consultation\",\n  \"notes\": \"Please schedule the patient within two weeks.\",\n  \"prior_authorization_code\": \"AUTH-12345\",\n  \"specialty\": \"Cardiology\",\n  \"location_id\": \"location-1\",\n  \"start_date\": \"2026-09-01\",\n  \"end_date\": \"2027-09-14\",\n  \"visits_allowed\": 14,\n  \"assigned_to_id\": \"STAFF-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/referrals/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"priority\": \"routine\",\n  \"status\": \"Sent\",\n  \"reason\": \"Specialist consultation\",\n  \"notes\": \"Please schedule the patient within two weeks.\",\n  \"prior_authorization_code\": \"AUTH-12345\",\n  \"specialty\": \"Cardiology\",\n  \"location_id\": \"location-1\",\n  \"start_date\": \"2026-09-01\",\n  \"end_date\": \"2027-09-14\",\n  \"visits_allowed\": 14,\n  \"assigned_to_id\": \"STAFF-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "referral_id": "<string>",
  "job_id": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

PATCH

referrals

{id}

Update a referral

curl --request PATCH \
  --url https://api.usecobalt.com/v1/referrals/{id} \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "priority": "routine",
  "status": "Sent",
  "reason": "Specialist consultation",
  "notes": "Please schedule the patient within two weeks.",
  "prior_authorization_code": "AUTH-12345",
  "specialty": "Cardiology",
  "location_id": "location-1",
  "start_date": "2026-09-01",
  "end_date": "2027-09-14",
  "visits_allowed": 14,
  "assigned_to_id": "STAFF-123",
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/referrals/{id}"

payload = {
    "priority": "routine",
    "status": "Sent",
    "reason": "Specialist consultation",
    "notes": "Please schedule the patient within two weeks.",
    "prior_authorization_code": "AUTH-12345",
    "specialty": "Cardiology",
    "location_id": "location-1",
    "start_date": "2026-09-01",
    "end_date": "2027-09-14",
    "visits_allowed": 14,
    "assigned_to_id": "STAFF-123",
    "callback_urls": ["https://example.com/webhooks/cobalt"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    priority: 'routine',
    status: 'Sent',
    reason: 'Specialist consultation',
    notes: 'Please schedule the patient within two weeks.',
    prior_authorization_code: 'AUTH-12345',
    specialty: 'Cardiology',
    location_id: 'location-1',
    start_date: '2026-09-01',
    end_date: '2027-09-14',
    visits_allowed: 14,
    assigned_to_id: 'STAFF-123',
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/referrals/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/referrals/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'priority' => 'routine',
    'status' => 'Sent',
    'reason' => 'Specialist consultation',
    'notes' => 'Please schedule the patient within two weeks.',
    'prior_authorization_code' => 'AUTH-12345',
    'specialty' => 'Cardiology',
    'location_id' => 'location-1',
    'start_date' => '2026-09-01',
    'end_date' => '2027-09-14',
    'visits_allowed' => 14,
    'assigned_to_id' => 'STAFF-123',
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/referrals/{id}"

	payload := strings.NewReader("{\n  \"priority\": \"routine\",\n  \"status\": \"Sent\",\n  \"reason\": \"Specialist consultation\",\n  \"notes\": \"Please schedule the patient within two weeks.\",\n  \"prior_authorization_code\": \"AUTH-12345\",\n  \"specialty\": \"Cardiology\",\n  \"location_id\": \"location-1\",\n  \"start_date\": \"2026-09-01\",\n  \"end_date\": \"2027-09-14\",\n  \"visits_allowed\": 14,\n  \"assigned_to_id\": \"STAFF-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.usecobalt.com/v1/referrals/{id}")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"priority\": \"routine\",\n  \"status\": \"Sent\",\n  \"reason\": \"Specialist consultation\",\n  \"notes\": \"Please schedule the patient within two weeks.\",\n  \"prior_authorization_code\": \"AUTH-12345\",\n  \"specialty\": \"Cardiology\",\n  \"location_id\": \"location-1\",\n  \"start_date\": \"2026-09-01\",\n  \"end_date\": \"2027-09-14\",\n  \"visits_allowed\": 14,\n  \"assigned_to_id\": \"STAFF-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/referrals/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"priority\": \"routine\",\n  \"status\": \"Sent\",\n  \"reason\": \"Specialist consultation\",\n  \"notes\": \"Please schedule the patient within two weeks.\",\n  \"prior_authorization_code\": \"AUTH-12345\",\n  \"specialty\": \"Cardiology\",\n  \"location_id\": \"location-1\",\n  \"start_date\": \"2026-09-01\",\n  \"end_date\": \"2027-09-14\",\n  \"visits_allowed\": 14,\n  \"assigned_to_id\": \"STAFF-123\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "referral_id": "<string>",
  "job_id": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

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.

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

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.",
    "prior_authorization_code": "AUTH-12345",
    "specialty": "Cardiology",
    "location_id": "loc-123"
}'

Update a Single Field

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

{
    "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

{
    "success": false,
    "message": "Invalid priority. Must be one of: routine, urgent, stat (case-insensitive)."
}

Invalid Status

{
    "success": false,
    "message": "Invalid status. Must be a non-empty string."
}

No Updatable Fields

{
    "success": false,
    "message": "No updatable fields provided. Supply at least one of: priority, status, reason, notes, prior_authorization_code, specialty, location_id."
}

Unexpected Fields

{
    "success": false,
    "message": "Unexpected fields in request body: foo. Updatable fields are: priority, status, reason, notes, prior_authorization_code, specialty, location_id."
}

Unknown Location

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

{
    "success": false,
    "message": "Location with EMR ID '99999' not found. Ensure the location has been synced."
}

Invalid Referral ID

{
    "success": false,
    "message": "Invalid referral ID format. Must be a valid UUID."
}

Referral Not Yet in the EMR

{
    "success": false,
    "message": "Referral has not been created in the EMR yet and cannot be updated."
}

Referral Not Found

{
    "success": false,
    "message": "Referral not found."
}

Webhook Notifications

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

Success

{
    "id": "<id-of-webhook-response>",
    "access_token_reference_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", "specialty", "location_id"]
    }
}

updated_fields lists the fields that were applied in this update.

Failure

{
    "id": "<id-of-webhook-response>",
    "access_token_reference_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 or specialty). Other failures omit it.

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Path Parameters

string

required

Cobalt referral ID (UUID, with or without dashes).

Body

application/json

priority

string

Referral priority (case-insensitive). One of: routine, urgent, stat.

Example:

"routine"

status

string

Referral status. Resolved against the EMR instance’s live status list by the worker.

Example:

"Sent"

reason

string

Reason for the referral.

Example:

"Specialist consultation"

notes

string

Free-text notes to write on the referral.

Example:

"Please schedule the patient within two weeks."

prior_authorization_code

string

Prior authorization code to write on the referral.

Example:

"AUTH-12345"

specialty

string

Referral specialty name. Resolved against the EMR instance’s live specialty list by the worker.

Example:

"Cardiology"

location_id

string

EMR location ID of the facility being referred to. Validated against the account’s locations and written as the referral’s to-facility.

Example:

"location-1"

start_date

string

Date the referral becomes valid (ISO 8601, YYYY-MM-DD).

Example:

"2026-09-01"

end_date

string

Date the referral expires (ISO 8601, YYYY-MM-DD). Must be on or after start_date.

Example:

"2027-09-14"

visits_allowed

integer

Number of visits the referral allows.

Required range: x >= 0

Example:

14

assigned_to_id

string

EMR staff ID of the user the referral is assigned to. Validated against the account’s synced staff list; valid ids are the ehr_id values from GET /v1/staff.

Example:

"STAFF-123"

callback_urls

string[]

URLs to receive the completion webhook for this update, in addition to the account webhook.

Example:

["https://example.com/webhooks/cobalt"]

Response

Referral update queued

success

boolean

required

message

string

required

referral_id

string

required

job_id

required

​Path Parameter

​Request Parameters

​Status Values

​Specialty

​To Facility

​Example Request

​Update a Single Field

​Example Response

​Error Responses

​Invalid Priority

​Invalid Status

​No Updatable Fields

​Unexpected Fields

​Unknown Location

​Invalid Referral ID

​Referral Not Yet in the EMR

​Referral Not Found

​Webhook Notifications

​Success

​Failure

Authorizations

Path Parameters

Body

Response

Path Parameter

Request Parameters

Status Values

Specialty

To Facility

Example Request

Update a Single Field

Example Response

Error Responses

Invalid Priority

Invalid Status

No Updatable Fields

Unexpected Fields

Unknown Location

Invalid Referral ID

Referral Not Yet in the EMR

Referral Not Found

Webhook Notifications

Success

Failure