curl --request POST \
--url https://api.usecobalt.com/v1/notes \
--header 'Content-Type: application/json' \
--header 'access_token: <api-key>' \
--header 'client_id: <api-key>' \
--header 'client_secret: <api-key>' \
--data '
{
"note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.",
"icd_10_codes": [
"R51",
"M54.5"
],
"cpt_codes": [
"99213"
],
"mrn": "12345",
"appointment_date": "2026-06-15",
"appointment_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"force": "false",
"callback_urls": [
"https://example.com/webhooks/cobalt"
]
}
'import requests
url = "https://api.usecobalt.com/v1/notes"
payload = {
"note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.",
"icd_10_codes": ["R51", "M54.5"],
"cpt_codes": ["99213"],
"mrn": "12345",
"appointment_date": "2026-06-15",
"appointment_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"force": "false",
"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.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({
note: 'Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.',
icd_10_codes: ['R51', 'M54.5'],
cpt_codes: ['99213'],
mrn: '12345',
appointment_date: '2026-06-15',
appointment_id: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
force: 'false',
callback_urls: ['https://example.com/webhooks/cobalt']
})
};
fetch('https://api.usecobalt.com/v1/notes', 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/notes",
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([
'note' => 'Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.',
'icd_10_codes' => [
'R51',
'M54.5'
],
'cpt_codes' => [
'99213'
],
'mrn' => '12345',
'appointment_date' => '2026-06-15',
'appointment_id' => 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
'force' => 'false',
'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/notes"
payload := strings.NewReader("{\n \"note\": \"Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.\",\n \"icd_10_codes\": [\n \"R51\",\n \"M54.5\"\n ],\n \"cpt_codes\": [\n \"99213\"\n ],\n \"mrn\": \"12345\",\n \"appointment_date\": \"2026-06-15\",\n \"appointment_id\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"force\": \"false\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\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/notes")
.header("client_id", "<api-key>")
.header("client_secret", "<api-key>")
.header("access_token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"note\": \"Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.\",\n \"icd_10_codes\": [\n \"R51\",\n \"M54.5\"\n ],\n \"cpt_codes\": [\n \"99213\"\n ],\n \"mrn\": \"12345\",\n \"appointment_date\": \"2026-06-15\",\n \"appointment_id\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"force\": \"false\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecobalt.com/v1/notes")
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 \"note\": \"Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.\",\n \"icd_10_codes\": [\n \"R51\",\n \"M54.5\"\n ],\n \"cpt_codes\": [\n \"99213\"\n ],\n \"mrn\": \"12345\",\n \"appointment_date\": \"2026-06-15\",\n \"appointment_id\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"force\": \"false\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "<string>",
"job_id": "<string>"
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}Create Note
Creates a note for a given appointment.
curl --request POST \
--url https://api.usecobalt.com/v1/notes \
--header 'Content-Type: application/json' \
--header 'access_token: <api-key>' \
--header 'client_id: <api-key>' \
--header 'client_secret: <api-key>' \
--data '
{
"note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.",
"icd_10_codes": [
"R51",
"M54.5"
],
"cpt_codes": [
"99213"
],
"mrn": "12345",
"appointment_date": "2026-06-15",
"appointment_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"force": "false",
"callback_urls": [
"https://example.com/webhooks/cobalt"
]
}
'import requests
url = "https://api.usecobalt.com/v1/notes"
payload = {
"note": "Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.",
"icd_10_codes": ["R51", "M54.5"],
"cpt_codes": ["99213"],
"mrn": "12345",
"appointment_date": "2026-06-15",
"appointment_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"force": "false",
"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.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({
note: 'Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.',
icd_10_codes: ['R51', 'M54.5'],
cpt_codes: ['99213'],
mrn: '12345',
appointment_date: '2026-06-15',
appointment_id: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
force: 'false',
callback_urls: ['https://example.com/webhooks/cobalt']
})
};
fetch('https://api.usecobalt.com/v1/notes', 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/notes",
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([
'note' => 'Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.',
'icd_10_codes' => [
'R51',
'M54.5'
],
'cpt_codes' => [
'99213'
],
'mrn' => '12345',
'appointment_date' => '2026-06-15',
'appointment_id' => 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
'force' => 'false',
'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/notes"
payload := strings.NewReader("{\n \"note\": \"Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.\",\n \"icd_10_codes\": [\n \"R51\",\n \"M54.5\"\n ],\n \"cpt_codes\": [\n \"99213\"\n ],\n \"mrn\": \"12345\",\n \"appointment_date\": \"2026-06-15\",\n \"appointment_id\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"force\": \"false\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\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/notes")
.header("client_id", "<api-key>")
.header("client_secret", "<api-key>")
.header("access_token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"note\": \"Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.\",\n \"icd_10_codes\": [\n \"R51\",\n \"M54.5\"\n ],\n \"cpt_codes\": [\n \"99213\"\n ],\n \"mrn\": \"12345\",\n \"appointment_date\": \"2026-06-15\",\n \"appointment_id\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"force\": \"false\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecobalt.com/v1/notes")
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 \"note\": \"Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics.\",\n \"icd_10_codes\": [\n \"R51\",\n \"M54.5\"\n ],\n \"cpt_codes\": [\n \"99213\"\n ],\n \"mrn\": \"12345\",\n \"appointment_date\": \"2026-06-15\",\n \"appointment_id\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"force\": \"false\",\n \"callback_urls\": [\n \"https://example.com/webhooks/cobalt\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "<string>",
"job_id": "<string>"
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}appointment_id. The appointment_id parameter should be the Cobalt appointment ID returned from API responses or GET endpoints, not the EHR appointment ID.note parameter accepts a structured object with separate fields for clinical documentation, along with optional ICD-10 and CPT codes. The note keys depend on the connected EHR: use the HPI format (hpi, exam, assessment, treatment) or the SOAP format (subjective, objective, assessment, plan), as the examples below show.
Example Request (HPI format)
# eClinicalWorks
curl -X POST https://api.usecobalt.com/v1/notes \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"appointment_id": "728948",
"note": {
"hpi": "Patient presents with persistent lower back pain for 2 weeks. Pain is described as dull and achy, rated 6/10. Worse with prolonged sitting and bending forward. Denies radiation to legs, numbness, or tingling. No bowel or bladder changes. Patient tried over-the-counter ibuprofen with minimal relief.",
"exam": "Vital signs: BP 128/82, HR 74, Temp 98.6°F. General: Alert and oriented x3, in no acute distress. MSK: Limited range of motion in lumbar spine with forward flexion. Tenderness to palpation over L4-L5 region. Negative straight leg raise bilaterally. Motor strength 5/5 in bilateral lower extremities. Sensation intact.",
"assessment": "Acute mechanical low back pain, likely lumbar strain. No red flags for serious pathology.",
"treatment": "Prescribed naproxen 500mg BID for 10 days. Recommended ice/heat therapy alternating every 20 minutes. Physical therapy referral placed for core strengthening and flexibility exercises. Patient educated on proper lifting mechanics and posture. Return precautions discussed including progressive neurological symptoms."
},
"icd_10_codes": ["M54.5", "M54.50"],
"cpt_codes": ["99213", "97110"]
}'
Example Request (SOAP format)
# Practice Fusion (cpt_codes are not written to the EHR)
curl -X POST https://api.usecobalt.com/v1/notes \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"appointment_id": "728948",
"note": {
"subjective": "Patient presents with persistent lower back pain for 2 weeks. Pain is described as dull and achy, rated 6/10. Worse with prolonged sitting and bending forward. Denies radiation to legs, numbness, or tingling.",
"objective": "Vital signs: BP 128/82, HR 74, Temp 98.6°F. Limited range of motion in lumbar spine with forward flexion. Tenderness to palpation over L4-L5 region. Negative straight leg raise bilaterally.",
"assessment": "Acute mechanical low back pain, likely lumbar strain. No red flags for serious pathology.",
"plan": "Prescribed naproxen 500mg BID for 10 days. Physical therapy referral placed for core strengthening. Return precautions discussed."
},
"icd_10_codes": ["M54.5", "M54.50"]
}'
Example Response
{
"success": true,
"message": "Note upload in progress. A webhook event will be sent upon completion.",
"job_id": 12345
}
Webhook Notifications
When the note processing is complete, we will send a webhook to your registered endpoint. Here are examples of what those webhook payloads will look like: See the Webhook Events reference for the full field breakdown and error codes.Success
{
"id": "evt_1J9X2q2eZvKYlo2CluR9g9gV",
"access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
"object": "event",
"created": "2023-10-27T10:30:00Z",
"type": "note.uploaded",
"job_id": 12345,
"data": {
"appointment_id": "728948",
"mrn": "12345",
"timezone": "America/New_York",
"status": "partial_success",
"icd_codes": {
"matched": [
{ "code": "E11.9", "name": "Type 2 diabetes mellitus without complications" }
],
"unmatched": [
{ "code": "Z00.00", "reason": "Code not found in EHR system" }
]
},
"cpt_codes": {
"matched": [
{ "code": "99213", "name": "Office/outpatient visit, established patient" }
],
"unmatched": []
}
}
}
Failure
{
"id": "evt_1J9X2q2eZvKYlo2CluR9g9gW",
"access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
"object": "event",
"created": "2023-10-27T10:35:00Z",
"type": "note.failed",
"job_id": 12345,
"data": {
"appointment_id": "728948",
"mrn": "12345",
"status": "failed",
"failure_reason": "Text contains \"]]>\" which cannot be used in CDATA blocks. Please remove this sequence from the note text.",
"reasons": [
{
"code": "UNSUPPORTED_CHARACTERS",
"description": "Text contains \"]]>\" which cannot be used in CDATA blocks. Please remove this sequence from the note text."
}
]
}
}
Authorizations
Body
Clinical note content. A plain string for scribe/dictation, or a structured object for RPA upload.
"Chief complaint: headache. Assessment: tension headache. Plan: OTC analgesics."
ICD-10 diagnosis codes. An array of codes, or an object shaped { codes: [...] } / { selected_codes: { codes: [...] } }.
["R51", "M54.5"]
CPT procedure codes.
["99213"]
Patient Medical Record Number. Provide mrn + appointment_date, or appointment_id, to identify the appointment.
"12345"
Appointment date (ISO 8601, YYYY-MM-DD). Used with mrn to identify the appointment.
"2026-06-15"
Cobalt appointment ID (UUID, with or without dashes). Alternative to mrn + appointment_date.
"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
When "true", upload the note even if the appointment is already processed. One of: "true", "false".
"false"
URLs to receive the completion webhook for this note, in addition to the account webhook.
["https://example.com/webhooks/cobalt"]