Fetch Document

Fetch a document

curl --request POST \
  --url https://api.usecobalt.com/v1/documents/fetch \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "document_id": "swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9",
  "document_ids": [
    "3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12"
  ],
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/documents/fetch"

payload = {
    "document_id": "swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9",
    "document_ids": ["3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12"],
    "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({
    document_id: 'swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9',
    document_ids: ['3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12'],
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/documents/fetch', 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/documents/fetch",
  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([
    'document_id' => 'swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9',
    'document_ids' => [
        '3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12'
    ],
    '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/documents/fetch"

	payload := strings.NewReader("{\n  \"document_id\": \"swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9\",\n  \"document_ids\": [\n    \"3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12\"\n  ],\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/documents/fetch")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_id\": \"swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9\",\n  \"document_ids\": [\n    \"3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12\"\n  ],\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"document_id\": \"swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9\",\n  \"document_ids\": [\n    \"3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12\"\n  ],\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>"
}

POST

documents

fetch

Fetch a document

curl --request POST \
  --url https://api.usecobalt.com/v1/documents/fetch \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "document_id": "swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9",
  "document_ids": [
    "3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12"
  ],
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/documents/fetch"

payload = {
    "document_id": "swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9",
    "document_ids": ["3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12"],
    "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({
    document_id: 'swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9',
    document_ids: ['3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12'],
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/documents/fetch', 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/documents/fetch",
  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([
    'document_id' => 'swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9',
    'document_ids' => [
        '3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12'
    ],
    '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/documents/fetch"

	payload := strings.NewReader("{\n  \"document_id\": \"swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9\",\n  \"document_ids\": [\n    \"3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12\"\n  ],\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/documents/fetch")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_id\": \"swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9\",\n  \"document_ids\": [\n    \"3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12\"\n  ],\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"document_id\": \"swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9\",\n  \"document_ids\": [\n    \"3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12\"\n  ],\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>"
}

Queues an on-demand fetch of a document’s file from the EMR. This is asynchronous: the endpoint returns a job_id, Cobalt retrieves the file from the EMR and stores it, then sends a document.live_fetch_completed webhook. Retrieve the file with GET /documents/. Depending on the EMR, the request takes either document_ids (a batch of 1-10 Cobalt document IDs) or a single document_id. See the request body below for which field your EMR uses.

Getting document IDs

Use the IDs Cobalt returns for EMR documents:

documents[].id on each patient in a patient live fetch: a file in the patient’s chart.
encounters[].visit_note_document_id on a patient live fetch, or visit_note_document_id on each appointment in an appointment live fetch: the encounter’s visit note, delivered as a PDF.

Cobalt document IDs are UUIDs, accepted with or without dashes. They are stable: the same EMR document always has the same ID, so you can store them.

Flow

POST /documents/fetch returns 202 and a job_id.
Cobalt fetches each file from the EMR and stores it. Visit notes are rendered to PDF.
A document.live_fetch_completed webhook is sent with a result per document.
GET /documents/{id} returns the file.

Example Request

curl -X POST "https://api.usecobalt.com/v1/documents/fetch" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12", "8a7b6c5d4e3f4a2b9c1d0e9f8a7b6c5d"]}'

Webhook

With document_ids, data.documents has one result per requested document. A document that could not be fetched has success: false and a message; the other documents in the batch are not affected.

{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "object": "event",
    "created": "2026-10-07T22:54:50Z",
    "type": "document.live_fetch_completed",
    "data": {
        "success": true,
        "documents": [
            {
                "id": "3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12",
                "success": true,
                "document_type": "visit_note",
                "file_name": "visit_note_159820.pdf",
                "mime_type": "application/pdf",
                "byte_size": 41040,
                "patient_mrn": "15322"
            },
            {
                "id": "8a7b6c5d4e3f4a2b9c1d0e9f8a7b6c5d",
                "success": false,
                "message": "Document not found."
            }
        ]
    }
}

Status Codes

202: Fetch accepted; results are delivered via webhook and files are retrievable at GET /documents/{id}.
400: Missing or invalid document_ids / document_id, more than 10 document_ids, or the connected EMR is not supported.
404: One or more document_ids are not documents of this linked account. The message lists them as sent.

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Body

application/json

document_id

string

required

Cobalt document id identifying the EMR document to fetch (e.g. from the patient live-fetch response).

Example:

"swf1_eyJtIjoiMjg3IiwiZiI6IjI2IiwiaSI6IjEwNDE5NTE3NyJ9"

document_ids

string[]

required

Cobalt document ids to fetch (1-10), e.g. documents[].id or visit_note_document_id from the patient or appointment live fetch. Each document's file is fetched from the EMR (visit notes are rendered to PDF) and stored; results arrive per document in the webhook.

Required array length: 1 - 10 elements

Example:

["3f1c2b7e9d4a4c6f8b2e1a0d5c7e9f12"]

callback_urls

string[]

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

Example:

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

Response

Document fetch accepted

success

boolean

required

message

string

required

job_id

required

​Getting document IDs

​Flow

​Example Request

​Webhook

​Status Codes

Authorizations

Body

Response

Getting document IDs

Flow

Example Request

Webhook

Status Codes