Update 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 '
{
  "status": "<string>",
  "reason": "<string>",
  "notes": "<string>"
}
'

import requests

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

payload = {
    "status": "<string>",
    "reason": "<string>",
    "notes": "<string>"
}
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({status: '<string>', reason: '<string>', notes: '<string>'})
};

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([
    'status' => '<string>',
    'reason' => '<string>',
    'notes' => '<string>'
  ]),
  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  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"notes\": \"<string>\"\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  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"notes\": \"<string>\"\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  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"notes\": \"<string>\"\n}"

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

{
  "success": true,
  "message": "Referral queued for update. A webhook event will be sent upon completion.",
  "referral_id": "<string>",
  "job_id": 123
}

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

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

{
  "success": true,
  "message": "Error updating referral."
}

PATCH

referrals

{id}

Update 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 '
{
  "status": "<string>",
  "reason": "<string>",
  "notes": "<string>"
}
'

import requests

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

payload = {
    "status": "<string>",
    "reason": "<string>",
    "notes": "<string>"
}
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({status: '<string>', reason: '<string>', notes: '<string>'})
};

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([
    'status' => '<string>',
    'reason' => '<string>',
    'notes' => '<string>'
  ]),
  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  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"notes\": \"<string>\"\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  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"notes\": \"<string>\"\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  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"notes\": \"<string>\"\n}"

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

{
  "success": true,
  "message": "Referral queued for update. A webhook event will be sent upon completion.",
  "referral_id": "<string>",
  "job_id": 123
}

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

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

{
  "success": true,
  "message": "Error updating 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.

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.

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."
}'

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."
}

Unexpected Fields

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

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"]
    }
}

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). 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). 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.

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.

Get Referrals Create Referring Provider

​Path Parameter

​Request Parameters

​Status Values

​Example Request

​Update a Single Field

​Example Response

​Error Responses

​Invalid Priority

​Invalid Status

​No Updatable Fields

​Unexpected Fields

​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

Example Request

Update a Single Field

Example Response

Error Responses

Invalid Priority

Invalid Status

No Updatable Fields

Unexpected Fields

Invalid Referral ID

Referral Not Yet in the EMR

Referral Not Found

Webhook Notifications

Success

Failure