Create Referral

Create a referral

curl --request POST \
  --url https://api.usecobalt.com/v1/referrals \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "patient_mrn": "12345",
  "referring_to_provider_ehr_id": "provider-123",
  "referring_from_provider_ehr_id": "provider-456",
  "priority": "routine",
  "reason": "Specialist consultation",
  "direction": "outgoing",
  "diagnosis_codes": [
    "I10",
    "E11.9"
  ],
  "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",
  "documents": [
    {
      "filename": "referral-letter.pdf",
      "content_base64": "JVBERi0xLjQKJcOkw7zDtsOfCg=="
    }
  ],
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ],
  "expires_at": "2027-06-15T14:30:00Z"
}
'

import requests

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

payload = {
    "patient_mrn": "12345",
    "referring_to_provider_ehr_id": "provider-123",
    "referring_from_provider_ehr_id": "provider-456",
    "priority": "routine",
    "reason": "Specialist consultation",
    "direction": "outgoing",
    "diagnosis_codes": ["I10", "E11.9"],
    "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",
    "documents": [
        {
            "filename": "referral-letter.pdf",
            "content_base64": "JVBERi0xLjQKJcOkw7zDtsOfCg=="
        }
    ],
    "callback_urls": ["https://example.com/webhooks/cobalt"],
    "expires_at": "2027-06-15T14:30:00Z"
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_mrn: '12345',
    referring_to_provider_ehr_id: 'provider-123',
    referring_from_provider_ehr_id: 'provider-456',
    priority: 'routine',
    reason: 'Specialist consultation',
    direction: 'outgoing',
    diagnosis_codes: ['I10', 'E11.9'],
    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',
    documents: [
      {
        filename: 'referral-letter.pdf',
        content_base64: 'JVBERi0xLjQKJcOkw7zDtsOfCg=='
      }
    ],
    callback_urls: ['https://example.com/webhooks/cobalt'],
    expires_at: '2027-06-15T14:30:00Z'
  })
};

fetch('https://api.usecobalt.com/v1/referrals', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'patient_mrn' => '12345',
    'referring_to_provider_ehr_id' => 'provider-123',
    'referring_from_provider_ehr_id' => 'provider-456',
    'priority' => 'routine',
    'reason' => 'Specialist consultation',
    'direction' => 'outgoing',
    'diagnosis_codes' => [
        'I10',
        'E11.9'
    ],
    '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',
    'documents' => [
        [
                'filename' => 'referral-letter.pdf',
                'content_base64' => 'JVBERi0xLjQKJcOkw7zDtsOfCg=='
        ]
    ],
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ],
    'expires_at' => '2027-06-15T14:30:00Z'
  ]),
  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"

	payload := strings.NewReader("{\n  \"patient_mrn\": \"12345\",\n  \"referring_to_provider_ehr_id\": \"provider-123\",\n  \"referring_from_provider_ehr_id\": \"provider-456\",\n  \"priority\": \"routine\",\n  \"reason\": \"Specialist consultation\",\n  \"direction\": \"outgoing\",\n  \"diagnosis_codes\": [\n    \"I10\",\n    \"E11.9\"\n  ],\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  \"documents\": [\n    {\n      \"filename\": \"referral-letter.pdf\",\n      \"content_base64\": \"JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n    }\n  ],\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ],\n  \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.usecobalt.com/v1/referrals")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"patient_mrn\": \"12345\",\n  \"referring_to_provider_ehr_id\": \"provider-123\",\n  \"referring_from_provider_ehr_id\": \"provider-456\",\n  \"priority\": \"routine\",\n  \"reason\": \"Specialist consultation\",\n  \"direction\": \"outgoing\",\n  \"diagnosis_codes\": [\n    \"I10\",\n    \"E11.9\"\n  ],\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  \"documents\": [\n    {\n      \"filename\": \"referral-letter.pdf\",\n      \"content_base64\": \"JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n    }\n  ],\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ],\n  \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.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  \"patient_mrn\": \"12345\",\n  \"referring_to_provider_ehr_id\": \"provider-123\",\n  \"referring_from_provider_ehr_id\": \"provider-456\",\n  \"priority\": \"routine\",\n  \"reason\": \"Specialist consultation\",\n  \"direction\": \"outgoing\",\n  \"diagnosis_codes\": [\n    \"I10\",\n    \"E11.9\"\n  ],\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  \"documents\": [\n    {\n      \"filename\": \"referral-letter.pdf\",\n      \"content_base64\": \"JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n    }\n  ],\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ],\n  \"expires_at\": \"2027-06-15T14:30:00Z\"\n}"

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

{
  "success": true,
  "message": "Request processed.",
  "referral_id": "c624cd97fc684b4587d98e258ab9ff10",
  "job_id": 1234
}

{
  "success": false,
  "message": "Bad request — missing or invalid parameters"
}

{
  "success": false,
  "message": "Unauthorized — missing or invalid credentials"
}

{
  "success": false,
  "message": "Resource not found"
}

{
  "success": false,
  "message": "Internal server error"
}

POST

referrals

Create a referral

curl --request POST \
  --url https://api.usecobalt.com/v1/referrals \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "patient_mrn": "12345",
  "referring_to_provider_ehr_id": "provider-123",
  "referring_from_provider_ehr_id": "provider-456",
  "priority": "routine",
  "reason": "Specialist consultation",
  "direction": "outgoing",
  "diagnosis_codes": [
    "I10",
    "E11.9"
  ],
  "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",
  "documents": [
    {
      "filename": "referral-letter.pdf",
      "content_base64": "JVBERi0xLjQKJcOkw7zDtsOfCg=="
    }
  ],
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ],
  "expires_at": "2027-06-15T14:30:00Z"
}
'

import requests

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

payload = {
    "patient_mrn": "12345",
    "referring_to_provider_ehr_id": "provider-123",
    "referring_from_provider_ehr_id": "provider-456",
    "priority": "routine",
    "reason": "Specialist consultation",
    "direction": "outgoing",
    "diagnosis_codes": ["I10", "E11.9"],
    "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",
    "documents": [
        {
            "filename": "referral-letter.pdf",
            "content_base64": "JVBERi0xLjQKJcOkw7zDtsOfCg=="
        }
    ],
    "callback_urls": ["https://example.com/webhooks/cobalt"],
    "expires_at": "2027-06-15T14:30:00Z"
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_mrn: '12345',
    referring_to_provider_ehr_id: 'provider-123',
    referring_from_provider_ehr_id: 'provider-456',
    priority: 'routine',
    reason: 'Specialist consultation',
    direction: 'outgoing',
    diagnosis_codes: ['I10', 'E11.9'],
    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',
    documents: [
      {
        filename: 'referral-letter.pdf',
        content_base64: 'JVBERi0xLjQKJcOkw7zDtsOfCg=='
      }
    ],
    callback_urls: ['https://example.com/webhooks/cobalt'],
    expires_at: '2027-06-15T14:30:00Z'
  })
};

fetch('https://api.usecobalt.com/v1/referrals', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'patient_mrn' => '12345',
    'referring_to_provider_ehr_id' => 'provider-123',
    'referring_from_provider_ehr_id' => 'provider-456',
    'priority' => 'routine',
    'reason' => 'Specialist consultation',
    'direction' => 'outgoing',
    'diagnosis_codes' => [
        'I10',
        'E11.9'
    ],
    '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',
    'documents' => [
        [
                'filename' => 'referral-letter.pdf',
                'content_base64' => 'JVBERi0xLjQKJcOkw7zDtsOfCg=='
        ]
    ],
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ],
    'expires_at' => '2027-06-15T14:30:00Z'
  ]),
  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"

	payload := strings.NewReader("{\n  \"patient_mrn\": \"12345\",\n  \"referring_to_provider_ehr_id\": \"provider-123\",\n  \"referring_from_provider_ehr_id\": \"provider-456\",\n  \"priority\": \"routine\",\n  \"reason\": \"Specialist consultation\",\n  \"direction\": \"outgoing\",\n  \"diagnosis_codes\": [\n    \"I10\",\n    \"E11.9\"\n  ],\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  \"documents\": [\n    {\n      \"filename\": \"referral-letter.pdf\",\n      \"content_base64\": \"JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n    }\n  ],\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ],\n  \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.usecobalt.com/v1/referrals")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"patient_mrn\": \"12345\",\n  \"referring_to_provider_ehr_id\": \"provider-123\",\n  \"referring_from_provider_ehr_id\": \"provider-456\",\n  \"priority\": \"routine\",\n  \"reason\": \"Specialist consultation\",\n  \"direction\": \"outgoing\",\n  \"diagnosis_codes\": [\n    \"I10\",\n    \"E11.9\"\n  ],\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  \"documents\": [\n    {\n      \"filename\": \"referral-letter.pdf\",\n      \"content_base64\": \"JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n    }\n  ],\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ],\n  \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.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  \"patient_mrn\": \"12345\",\n  \"referring_to_provider_ehr_id\": \"provider-123\",\n  \"referring_from_provider_ehr_id\": \"provider-456\",\n  \"priority\": \"routine\",\n  \"reason\": \"Specialist consultation\",\n  \"direction\": \"outgoing\",\n  \"diagnosis_codes\": [\n    \"I10\",\n    \"E11.9\"\n  ],\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  \"documents\": [\n    {\n      \"filename\": \"referral-letter.pdf\",\n      \"content_base64\": \"JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n    }\n  ],\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ],\n  \"expires_at\": \"2027-06-15T14:30:00Z\"\n}"

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

{
  "success": true,
  "message": "Request processed.",
  "referral_id": "c624cd97fc684b4587d98e258ab9ff10",
  "job_id": 1234
}

{
  "success": false,
  "message": "Bad request — missing or invalid parameters"
}

{
  "success": false,
  "message": "Unauthorized — missing or invalid credentials"
}

{
  "success": false,
  "message": "Resource not found"
}

{
  "success": false,
  "message": "Internal server error"
}

Referrals are created in the provider’s EMR using an asynchronous processing model. Creating a referral this way is not instantaneous. Instead of leaving your POST 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 referral has been created in the EMR. This gives you flexibility around your user experience. For example, when you first make the /referrals call you can display a Processing status to your user, and when you receive the webhook notification you can update that to Completed.

Request Parameters

Required Fields

patient_mrn (string, required): The patient’s medical record number. The patient must already be synced to Cobalt.
referring_from_provider_ehr_id (string, required): EMR ID of the provider the referral is coming from.
referring_to_provider_ehr_id (string, required): EMR ID of the provider the referral is going to.
direction (string, required): Direction of the referral — incoming or outgoing.
priority (string, required): Referral priority — routine, urgent, or stat.
reason (string, required): Reason for the referral.

Optional Fields

diagnosis_codes (array of strings, optional): ICD-10 diagnosis codes associated with the referral.
documents (array, optional): Documents to attach to the referral in the EMR. Each entry is an object with filename and content_base64. See Attaching Documents below.
prior_authorization_code (string, optional): Prior authorization code to write on the referral.
specialty (string, optional): Referral specialty name — e.g. "Cardiology". Resolved against the EMR instance’s live specialty list when the referral is processed; an unrecognized specialty fails with a referral.failed webhook (error_type: "ecw_validation_failure").
location_id (string, optional): EMR location ID of the facility being referred to. Validated synchronously against the account’s synced locations — an unknown location returns a 404 and the referral is not queued. Resolve IDs with GET /v1/locations (use the location’s emr_id).

Direction and Provider Validation

The two provider IDs are validated against different directories depending on the referral’s direction:

Direction	`referring_from_provider_ehr_id` validated against	`referring_to_provider_ehr_id` validated against
`incoming`	Referring providers directory	Providers directory
`outgoing`	Providers directory	Referring providers directory

Pass 0 for a provider ID when there is no provider on that side. Providers must already be synced — use GET /v1/providers and GET /v1/referring-providers to resolve IDs.

Attaching Documents

Documents are optional and supplied inline as base64. Each document is an object:

{
  "filename": "consult-note.pdf",
  "content_base64": "JVBERi0xLjQKJ..."
}

filename must include a file extension (e.g. report.pdf).
content_base64 must be non-empty, valid base64.

Documents are attached to the referral in the EMR after the referral itself is created. Because the referral already exists at that point, attachment failures are non-fatal: the referral is still created and the webhook reports how many attachments succeeded and failed.

Requests carrying inline documents can be large. The POST /v1/referrals endpoint accepts request bodies up to 25 MB.

Example Request

curl -X POST https://api.usecobalt.com/v1/referrals \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "patient_mrn": "1234567",
    "referring_from_provider_ehr_id": "PROV-001",
    "referring_to_provider_ehr_id": "PROV-002",
    "direction": "outgoing",
    "priority": "urgent",
    "reason": "Cardiology consultation",
    "diagnosis_codes": ["I10", "Z87.39"]
}'

Request with Documents

curl -X POST https://api.usecobalt.com/v1/referrals \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "patient_mrn": "1234567",
    "referring_from_provider_ehr_id": "PROV-001",
    "referring_to_provider_ehr_id": "PROV-002",
    "direction": "outgoing",
    "priority": "routine",
    "reason": "Dermatology referral",
    "documents": [
        { "filename": "consult-note.pdf", "content_base64": "JVBERi0xLjQKJ..." }
    ]
}'

Example Response

{
    "success": true,
    "message": "Referral queued for creation. 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). This is echoed back in the webhook payload so you can correlate the two.
job_id: Job execution identifier for tracking the async operation.

Error Responses

Missing Required Field

{
    "success": false,
    "message": "Missing required fields: patient_mrn, reason."
}

Invalid Priority

{
    "success": false,
    "message": "Invalid priority. Must be one of: routine, urgent, stat."
}

Invalid Direction

{
    "success": false,
    "message": "Invalid direction. Must be one of: incoming, outgoing."
}

Invalid Document

{
    "success": false,
    "message": "documents[0].filename must include a file extension (e.g. \"report.pdf\")."
}

Patient Not Found

{
    "success": false,
    "message": "Patient with MRN '1234567' not found. Ensure the patient has been synced."
}

Unknown Provider

{
    "success": false,
    "message": "Unknown provider(s): referring_to_provider_ehr_id 'PROV-002' was not found in referring providers. Ensure the provider has been synced."
}

Unknown Location

Returned when location_id does not match a synced location for the account.

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

User Not Found

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

This indicates an issue with your access token.

Webhook Notifications

When the referral 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.created",
    "job_id": "12345",
    "data": {
        "referral_id": "123e4567e89b12d3a456426614174000",
        "ehr_id": "REF-00123",
        "patient_mrn": "1234567",
        "from_provider_ehr_id": "PROV-001",
        "to_provider_ehr_id": "PROV-002",
        "direction": "outgoing",
        "documents_attached": 1,
        "documents_failed": 0
    }
}

Note: documents_attached and documents_failed are only included when the request contained documents.

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": "Unable to create referral in eCW. ECW rejected the request or returned an unexpected response."
    }
}

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Body

application/json

patient_mrn

string

required

Medical Record Number of the patient the referral is for.

Example:

"12345"

referring_to_provider_ehr_id

string

required

EHR ID of the provider being referred to. Validated against the provider directory for the referral direction; "0" means no provider on that side.

Example:

"provider-123"

referring_from_provider_ehr_id

string

required

EHR ID of the provider making the referral. Validated against the provider directory for the referral direction; "0" means no provider on that side.

Example:

"provider-456"

priority

string

required

Referral priority. One of: routine, urgent, stat.

Example:

"routine"

reason

string

required

Reason for the referral.

Example:

"Specialist consultation"

direction

string

required

Referral direction. One of: incoming, outgoing.

Example:

"outgoing"

diagnosis_codes

string[]

ICD-10 diagnosis codes associated with the referral.

Example:

["I10", "E11.9"]

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). Defaults to the referral creation date.

Example:

"2026-09-01"

end_date

string

Date the referral expires (ISO 8601, YYYY-MM-DD). Must be on or after start_date. Defaults to one year 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"

documents

object[]

Documents to attach to the referral, supplied inline. Each item is { filename, content_base64 }; filename must include a file extension.

Show child attributes

Example:

[
  {
    "filename": "referral-letter.pdf",
    "content_base64": "JVBERi0xLjQKJcOkw7zDtsOfCg=="
  }
]

callback_urls

string[]

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

Example:

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

expires_at

string<date-time> | null

Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.

Example:

"2027-06-15T14:30:00Z"

Response

Referral queued for creation

success

boolean

required

Example:

true

message

string

required

Example:

"Request processed."

referral_id

string

required

Example:

"c624cd97fc684b4587d98e258ab9ff10"

job_id

required

Example:

1234

​Request Parameters

​Required Fields

​Optional Fields

​Direction and Provider Validation

​Attaching Documents

​Example Request

​Request with Documents

​Example Response

​Error Responses

​Missing Required Field

​Invalid Priority

​Invalid Direction

​Invalid Document

​Patient Not Found

​Unknown Provider

​Unknown Location

​User Not Found

​Webhook Notifications

​Success

​Failure

Authorizations

Body

Response

Request Parameters

Required Fields

Optional Fields

Direction and Provider Validation

Attaching Documents

Example Request

Request with Documents

Example Response

Error Responses

Missing Required Field

Invalid Priority

Invalid Direction

Invalid Document

Patient Not Found

Unknown Provider

Unknown Location

User Not Found

Webhook Notifications

Success

Failure