Create 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": "<string>",
  "referring_from_provider_ehr_id": "<string>",
  "referring_to_provider_ehr_id": "<string>",
  "reason": "<string>",
  "diagnosis_codes": [
    "<string>"
  ],
  "documents": [
    {
      "filename": "<string>",
      "content_base64": "<string>"
    }
  ]
}
'

import requests

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

payload = {
    "patient_mrn": "<string>",
    "referring_from_provider_ehr_id": "<string>",
    "referring_to_provider_ehr_id": "<string>",
    "reason": "<string>",
    "diagnosis_codes": ["<string>"],
    "documents": [
        {
            "filename": "<string>",
            "content_base64": "<string>"
        }
    ]
}
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: '<string>',
    referring_from_provider_ehr_id: '<string>',
    referring_to_provider_ehr_id: '<string>',
    reason: '<string>',
    diagnosis_codes: ['<string>'],
    documents: [{filename: '<string>', content_base64: '<string>'}]
  })
};

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' => '<string>',
    'referring_from_provider_ehr_id' => '<string>',
    'referring_to_provider_ehr_id' => '<string>',
    'reason' => '<string>',
    'diagnosis_codes' => [
        '<string>'
    ],
    'documents' => [
        [
                'filename' => '<string>',
                'content_base64' => '<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"

	payload := strings.NewReader("{\n  \"patient_mrn\": \"<string>\",\n  \"referring_from_provider_ehr_id\": \"<string>\",\n  \"referring_to_provider_ehr_id\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"diagnosis_codes\": [\n    \"<string>\"\n  ],\n  \"documents\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_base64\": \"<string>\"\n    }\n  ]\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\": \"<string>\",\n  \"referring_from_provider_ehr_id\": \"<string>\",\n  \"referring_to_provider_ehr_id\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"diagnosis_codes\": [\n    \"<string>\"\n  ],\n  \"documents\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_base64\": \"<string>\"\n    }\n  ]\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\": \"<string>\",\n  \"referring_from_provider_ehr_id\": \"<string>\",\n  \"referring_to_provider_ehr_id\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"diagnosis_codes\": [\n    \"<string>\"\n  ],\n  \"documents\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_base64\": \"<string>\"\n    }\n  ]\n}"

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

{
  "success": true,
  "message": "Referral queued for creation. 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."
}

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

{
  "success": true,
  "message": "Error creating referral.",
  "referral_id": "<string>"
}

POST

referrals

Create 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": "<string>",
  "referring_from_provider_ehr_id": "<string>",
  "referring_to_provider_ehr_id": "<string>",
  "reason": "<string>",
  "diagnosis_codes": [
    "<string>"
  ],
  "documents": [
    {
      "filename": "<string>",
      "content_base64": "<string>"
    }
  ]
}
'

import requests

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

payload = {
    "patient_mrn": "<string>",
    "referring_from_provider_ehr_id": "<string>",
    "referring_to_provider_ehr_id": "<string>",
    "reason": "<string>",
    "diagnosis_codes": ["<string>"],
    "documents": [
        {
            "filename": "<string>",
            "content_base64": "<string>"
        }
    ]
}
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: '<string>',
    referring_from_provider_ehr_id: '<string>',
    referring_to_provider_ehr_id: '<string>',
    reason: '<string>',
    diagnosis_codes: ['<string>'],
    documents: [{filename: '<string>', content_base64: '<string>'}]
  })
};

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' => '<string>',
    'referring_from_provider_ehr_id' => '<string>',
    'referring_to_provider_ehr_id' => '<string>',
    'reason' => '<string>',
    'diagnosis_codes' => [
        '<string>'
    ],
    'documents' => [
        [
                'filename' => '<string>',
                'content_base64' => '<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"

	payload := strings.NewReader("{\n  \"patient_mrn\": \"<string>\",\n  \"referring_from_provider_ehr_id\": \"<string>\",\n  \"referring_to_provider_ehr_id\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"diagnosis_codes\": [\n    \"<string>\"\n  ],\n  \"documents\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_base64\": \"<string>\"\n    }\n  ]\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\": \"<string>\",\n  \"referring_from_provider_ehr_id\": \"<string>\",\n  \"referring_to_provider_ehr_id\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"diagnosis_codes\": [\n    \"<string>\"\n  ],\n  \"documents\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_base64\": \"<string>\"\n    }\n  ]\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\": \"<string>\",\n  \"referring_from_provider_ehr_id\": \"<string>\",\n  \"referring_to_provider_ehr_id\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"diagnosis_codes\": [\n    \"<string>\"\n  ],\n  \"documents\": [\n    {\n      \"filename\": \"<string>\",\n      \"content_base64\": \"<string>\"\n    }\n  ]\n}"

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

{
  "success": true,
  "message": "Referral queued for creation. 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."
}

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

{
  "success": true,
  "message": "Error creating referral.",
  "referral_id": "<string>"
}

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.

Creating referrals is currently supported for eClinicalWorks.

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.

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

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

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. For incoming referrals this is validated against the referring providers directory; for outgoing referrals it is validated against the providers directory. Pass 0 if there is no provider on this side.

referring_to_provider_ehr_id

string

required

EMR ID of the provider the referral is going to. For incoming referrals this is validated against the providers directory; for outgoing referrals it is validated against the referring providers directory. Pass 0 if there is no provider on this side.

direction

enum<string>

required

Direction of the referral. incoming means the referral is coming into your organization; outgoing means it is being sent out.

Available options:

incoming,

outgoing

priority

enum<string>

required

Referral priority.

Available options:

routine,

urgent,

stat

reason

string

required

Reason for the referral.

diagnosis_codes

string[]

Optional ICD-10 diagnosis codes associated with the referral.

documents

object[]

Optional documents to attach to the referral in the EMR. Each entry is supplied inline as base64. Document attachment happens after the referral is created and attachment failures are non-fatal.

Show child attributes

Response

Referral queued successfully

success

boolean

message

string

Example:

"Referral queued for creation. 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.

Update Provider by EMR ID Get Referrals

​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

​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

User Not Found

Webhook Notifications

Success

Failure