Create Order - Documentation

Create an order

curl --request POST \
  --url https://api.usecobalt.com/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "type": "lab",
  "patient_mrn": "12345",
  "item_id": "<string>",
  "name": "<string>",
  "provider_id": "<string>",
  "facility_id": "<string>",
  "assigned_to_id": "<string>",
  "order_date": "2026-03-15",
  "collected_date": "<string>",
  "collection_time": "<string>",
  "performed_date": "<string>",
  "high_priority": true,
  "notes": "<string>",
  "clinical_info": "<string>",
  "callback_urls": [
    "<string>"
  ]
}
'

import requests

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

payload = {
    "type": "lab",
    "patient_mrn": "12345",
    "item_id": "<string>",
    "name": "<string>",
    "provider_id": "<string>",
    "facility_id": "<string>",
    "assigned_to_id": "<string>",
    "order_date": "2026-03-15",
    "collected_date": "<string>",
    "collection_time": "<string>",
    "performed_date": "<string>",
    "high_priority": True,
    "notes": "<string>",
    "clinical_info": "<string>",
    "callback_urls": ["<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({
    type: 'lab',
    patient_mrn: '12345',
    item_id: '<string>',
    name: '<string>',
    provider_id: '<string>',
    facility_id: '<string>',
    assigned_to_id: '<string>',
    order_date: '2026-03-15',
    collected_date: '<string>',
    collection_time: '<string>',
    performed_date: '<string>',
    high_priority: true,
    notes: '<string>',
    clinical_info: '<string>',
    callback_urls: ['<string>']
  })
};

fetch('https://api.usecobalt.com/v1/orders', 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/orders",
  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([
    'type' => 'lab',
    'patient_mrn' => '12345',
    'item_id' => '<string>',
    'name' => '<string>',
    'provider_id' => '<string>',
    'facility_id' => '<string>',
    'assigned_to_id' => '<string>',
    'order_date' => '2026-03-15',
    'collected_date' => '<string>',
    'collection_time' => '<string>',
    'performed_date' => '<string>',
    'high_priority' => true,
    'notes' => '<string>',
    'clinical_info' => '<string>',
    'callback_urls' => [
        '<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/orders"

	payload := strings.NewReader("{\n  \"type\": \"lab\",\n  \"patient_mrn\": \"12345\",\n  \"item_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"provider_id\": \"<string>\",\n  \"facility_id\": \"<string>\",\n  \"assigned_to_id\": \"<string>\",\n  \"order_date\": \"2026-03-15\",\n  \"collected_date\": \"<string>\",\n  \"collection_time\": \"<string>\",\n  \"performed_date\": \"<string>\",\n  \"high_priority\": true,\n  \"notes\": \"<string>\",\n  \"clinical_info\": \"<string>\",\n  \"callback_urls\": [\n    \"<string>\"\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/orders")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"lab\",\n  \"patient_mrn\": \"12345\",\n  \"item_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"provider_id\": \"<string>\",\n  \"facility_id\": \"<string>\",\n  \"assigned_to_id\": \"<string>\",\n  \"order_date\": \"2026-03-15\",\n  \"collected_date\": \"<string>\",\n  \"collection_time\": \"<string>\",\n  \"performed_date\": \"<string>\",\n  \"high_priority\": true,\n  \"notes\": \"<string>\",\n  \"clinical_info\": \"<string>\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"type\": \"lab\",\n  \"patient_mrn\": \"12345\",\n  \"item_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"provider_id\": \"<string>\",\n  \"facility_id\": \"<string>\",\n  \"assigned_to_id\": \"<string>\",\n  \"order_date\": \"2026-03-15\",\n  \"collected_date\": \"<string>\",\n  \"collection_time\": \"<string>\",\n  \"performed_date\": \"<string>\",\n  \"high_priority\": true,\n  \"notes\": \"<string>\",\n  \"clinical_info\": \"<string>\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}"

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

{
  "success": true,
  "status": "<string>",
  "message": "<string>",
  "job_id": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

POST

orders

Create an order

curl --request POST \
  --url https://api.usecobalt.com/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "type": "lab",
  "patient_mrn": "12345",
  "item_id": "<string>",
  "name": "<string>",
  "provider_id": "<string>",
  "facility_id": "<string>",
  "assigned_to_id": "<string>",
  "order_date": "2026-03-15",
  "collected_date": "<string>",
  "collection_time": "<string>",
  "performed_date": "<string>",
  "high_priority": true,
  "notes": "<string>",
  "clinical_info": "<string>",
  "callback_urls": [
    "<string>"
  ]
}
'

import requests

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

payload = {
    "type": "lab",
    "patient_mrn": "12345",
    "item_id": "<string>",
    "name": "<string>",
    "provider_id": "<string>",
    "facility_id": "<string>",
    "assigned_to_id": "<string>",
    "order_date": "2026-03-15",
    "collected_date": "<string>",
    "collection_time": "<string>",
    "performed_date": "<string>",
    "high_priority": True,
    "notes": "<string>",
    "clinical_info": "<string>",
    "callback_urls": ["<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({
    type: 'lab',
    patient_mrn: '12345',
    item_id: '<string>',
    name: '<string>',
    provider_id: '<string>',
    facility_id: '<string>',
    assigned_to_id: '<string>',
    order_date: '2026-03-15',
    collected_date: '<string>',
    collection_time: '<string>',
    performed_date: '<string>',
    high_priority: true,
    notes: '<string>',
    clinical_info: '<string>',
    callback_urls: ['<string>']
  })
};

fetch('https://api.usecobalt.com/v1/orders', 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/orders",
  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([
    'type' => 'lab',
    'patient_mrn' => '12345',
    'item_id' => '<string>',
    'name' => '<string>',
    'provider_id' => '<string>',
    'facility_id' => '<string>',
    'assigned_to_id' => '<string>',
    'order_date' => '2026-03-15',
    'collected_date' => '<string>',
    'collection_time' => '<string>',
    'performed_date' => '<string>',
    'high_priority' => true,
    'notes' => '<string>',
    'clinical_info' => '<string>',
    'callback_urls' => [
        '<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/orders"

	payload := strings.NewReader("{\n  \"type\": \"lab\",\n  \"patient_mrn\": \"12345\",\n  \"item_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"provider_id\": \"<string>\",\n  \"facility_id\": \"<string>\",\n  \"assigned_to_id\": \"<string>\",\n  \"order_date\": \"2026-03-15\",\n  \"collected_date\": \"<string>\",\n  \"collection_time\": \"<string>\",\n  \"performed_date\": \"<string>\",\n  \"high_priority\": true,\n  \"notes\": \"<string>\",\n  \"clinical_info\": \"<string>\",\n  \"callback_urls\": [\n    \"<string>\"\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/orders")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"lab\",\n  \"patient_mrn\": \"12345\",\n  \"item_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"provider_id\": \"<string>\",\n  \"facility_id\": \"<string>\",\n  \"assigned_to_id\": \"<string>\",\n  \"order_date\": \"2026-03-15\",\n  \"collected_date\": \"<string>\",\n  \"collection_time\": \"<string>\",\n  \"performed_date\": \"<string>\",\n  \"high_priority\": true,\n  \"notes\": \"<string>\",\n  \"clinical_info\": \"<string>\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"type\": \"lab\",\n  \"patient_mrn\": \"12345\",\n  \"item_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"provider_id\": \"<string>\",\n  \"facility_id\": \"<string>\",\n  \"assigned_to_id\": \"<string>\",\n  \"order_date\": \"2026-03-15\",\n  \"collected_date\": \"<string>\",\n  \"collection_time\": \"<string>\",\n  \"performed_date\": \"<string>\",\n  \"high_priority\": true,\n  \"notes\": \"<string>\",\n  \"clinical_info\": \"<string>\",\n  \"callback_urls\": [\n    \"<string>\"\n  ]\n}"

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

{
  "success": true,
  "status": "<string>",
  "message": "<string>",
  "job_id": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

Orders are created asynchronously: a valid request returns immediately with a 202, and an order.created webhook is sent when processing completes. If creation fails terminally, an order.create_failed webhook is sent instead. Identify the test or procedure to order with either item_id or name. Discover valid values via Search Order Catalog. When both are provided, item_id wins. Creating orders is only supported for eClinicalWorks.

Request Parameters

Required Fields

type (string, required): Order type. One of lab, imaging, or procedure.
patient_mrn (string, required): Medical Record Number of the patient the order is for.

One of the following is also required:

item_id (string): EMR catalog id of the test/procedure to order. Discover ids via POST /v1/orders/catalog/fetch.
name (string): Catalog name of the test/procedure, resolved against the catalog when item_id is omitted.

Optional Fields

provider_id (string, optional): EMR id of the ordering provider.
facility_id (string, optional): EMR id of the ordering facility/location.
assigned_to_id (string, optional): EMR staff id the order is assigned to.
order_date (string, optional): Order date (ISO 8601, YYYY-MM-DD).
collected_date (string, optional): Specimen collection date (ISO 8601, YYYY-MM-DD). Labs.
collection_time (string, optional): Specimen collection time, e.g. "12:58 PM".
performed_date (string, optional): Performed date (ISO 8601, YYYY-MM-DD). Diagnostic imaging.
high_priority (boolean, optional): Flag the order high priority.
notes (string, optional): Order notes.
clinical_info (string, optional): Clinical information for the order.
callback_urls (string[], optional): URLs to receive the order.created webhook, in addition to the account webhook.

Example Requests

By item_id
By name

curl -X POST https://api.usecobalt.com/v1/orders \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "type": "lab",
    "patient_mrn": "12345",
    "item_id": "80048",
    "provider_id": "789",
    "facility_id": "25",
    "collected_date": "2026-03-15",
    "collection_time": "12:58 PM"
}'

curl -X POST https://api.usecobalt.com/v1/orders \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "type": "imaging",
    "patient_mrn": "12345",
    "name": "Chest X-Ray",
    "provider_id": "789",
    "performed_date": "2026-03-15",
    "high_priority": true,
    "clinical_info": "Persistent cough, rule out pneumonia."
}'

Example Response

{
  "success": true,
  "status": "queued",
  "message": "Order queued for creation. An order.created webhook will be sent when it completes.",
  "job_id": 12345
}

Error Responses

Missing Required Field

{
  "success": false,
  "message": "Missing required field: patient_mrn"
}

Missing Order Identifier

{
  "success": false,
  "message": "Provide either item_id or name to identify the order."
}

Webhook Notifications

When order processing completes, we send a webhook to your registered endpoint.

Success

{
  "id": "evt_1J9X2q2eZvKYlo2CluR9g9gV",
  "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
  "object": "event",
  "created": "2025-10-09T10:30:00Z",
  "type": "order.created",
  "job_id": "12345",
  "data": {
    "emr_order_id": "998877",
    "emr_encounter_id": "445566",
    "patient_mrn": "12345"
  }
}

Failure

{
  "id": "evt_1J9X2q2eZvKYlo2CluR9g9gW",
  "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
  "object": "event",
  "created": "2025-10-09T10:35:00Z",
  "type": "order.create_failed",
  "job_id": "12345",
  "data": {
    "patient_mrn": "12345",
    "failure_reason": "Order create failed after multiple attempts. Please try again later or contact support."
  }
}

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Body

application/json

type

enum<string>

required

Order type.

Available options:

lab,

imaging,

procedure

Example:

"lab"

patient_mrn

string

required

Medical Record Number of the patient the order is for.

Example:

"12345"

item_id

string

EMR catalog id of the test/procedure to order. Provide item_id OR name (enforced in the controller); item_id wins when both are given. Discover ids via POST /v1/orders/catalog/fetch.

name

string

Catalog name of the test/procedure to order, resolved against the catalog when item_id is omitted.

provider_id

string

EMR id of the ordering provider.

facility_id

string

EMR id of the ordering facility/location.

assigned_to_id

string

EMR staff id the order is assigned to.

order_date

string

Order date (ISO 8601, YYYY-MM-DD).

Example:

"2026-03-15"

collected_date

string

Specimen collection date (ISO 8601, YYYY-MM-DD). Labs.

collection_time

string

Specimen collection time, e.g. "12:58 PM".

performed_date

string

Performed date (ISO 8601, YYYY-MM-DD). Diagnostic imaging.

high_priority

boolean

Flag the order high priority.

notes

string

Order notes.

clinical_info

string

Clinical information for the order.

callback_urls

string[]

URLs to receive the order.created webhook, in addition to the account webhook.

Response

Queued for processing

success

boolean

required

status

string

required

message

string

required

job_id

required

​Request Parameters

​Required Fields

​Optional Fields

​Example Requests

​Example Response

​Error Responses

​Missing Required Field

​Missing Order Identifier

​Webhook Notifications

​Success

​Failure

Authorizations

Body

Response

Request Parameters

Required Fields

Optional Fields

Example Requests

Example Response

Error Responses

Missing Required Field

Missing Order Identifier

Webhook Notifications

Success

Failure