Update Patient Insurance

Update a patient insurance record

curl --request PATCH \
  --url https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances/{emr_insurance_id} \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "member_id": "MEM123456789",
  "group_id": "GRP98999",
  "insurance_provider_id": "insurance-provider-123",
  "insurance_payer_id": "98999",
  "insurance_name": "Blue Cross Anthem",
  "subscriber_demographics": {
    "first_name": "Jane",
    "last_name": "Doe",
    "street_line_1": "123 Main Street",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "sex": "F",
    "dob": "1980-01-15",
    "phone": "555-123-4567"
  },
  "relationship_to_subscriber": "self",
  "insurance_policy_type": "PPO",
  "insurance_sequence": "primary",
  "plan_begin_date": "2026-01-01",
  "plan_end_date": "2026-12-31",
  "copayment": 25,
  "telehealth_copayment": 10,
  "include_inactive_patients": false,
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ],
  "expires_at": "2027-06-15T14:30:00Z"
}
'

import requests

url = "https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances/{emr_insurance_id}"

payload = {
    "member_id": "MEM123456789",
    "group_id": "GRP98999",
    "insurance_provider_id": "insurance-provider-123",
    "insurance_payer_id": "98999",
    "insurance_name": "Blue Cross Anthem",
    "subscriber_demographics": {
        "first_name": "Jane",
        "last_name": "Doe",
        "street_line_1": "123 Main Street",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90001",
        "sex": "F",
        "dob": "1980-01-15",
        "phone": "555-123-4567"
    },
    "relationship_to_subscriber": "self",
    "insurance_policy_type": "PPO",
    "insurance_sequence": "primary",
    "plan_begin_date": "2026-01-01",
    "plan_end_date": "2026-12-31",
    "copayment": 25,
    "telehealth_copayment": 10,
    "include_inactive_patients": False,
    "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.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    member_id: 'MEM123456789',
    group_id: 'GRP98999',
    insurance_provider_id: 'insurance-provider-123',
    insurance_payer_id: '98999',
    insurance_name: 'Blue Cross Anthem',
    subscriber_demographics: {
      first_name: 'Jane',
      last_name: 'Doe',
      street_line_1: '123 Main Street',
      city: 'Los Angeles',
      state: 'CA',
      zip: '90001',
      sex: 'F',
      dob: '1980-01-15',
      phone: '555-123-4567'
    },
    relationship_to_subscriber: 'self',
    insurance_policy_type: 'PPO',
    insurance_sequence: 'primary',
    plan_begin_date: '2026-01-01',
    plan_end_date: '2026-12-31',
    copayment: 25,
    telehealth_copayment: 10,
    include_inactive_patients: false,
    callback_urls: ['https://example.com/webhooks/cobalt'],
    expires_at: '2027-06-15T14:30:00Z'
  })
};

fetch('https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances/{emr_insurance_id}', 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/patients/{patient_mrn}/insurances/{emr_insurance_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'member_id' => 'MEM123456789',
    'group_id' => 'GRP98999',
    'insurance_provider_id' => 'insurance-provider-123',
    'insurance_payer_id' => '98999',
    'insurance_name' => 'Blue Cross Anthem',
    'subscriber_demographics' => [
        'first_name' => 'Jane',
        'last_name' => 'Doe',
        'street_line_1' => '123 Main Street',
        'city' => 'Los Angeles',
        'state' => 'CA',
        'zip' => '90001',
        'sex' => 'F',
        'dob' => '1980-01-15',
        'phone' => '555-123-4567'
    ],
    'relationship_to_subscriber' => 'self',
    'insurance_policy_type' => 'PPO',
    'insurance_sequence' => 'primary',
    'plan_begin_date' => '2026-01-01',
    'plan_end_date' => '2026-12-31',
    'copayment' => 25,
    'telehealth_copayment' => 10,
    'include_inactive_patients' => false,
    '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/patients/{patient_mrn}/insurances/{emr_insurance_id}"

	payload := strings.NewReader("{\n  \"member_id\": \"MEM123456789\",\n  \"group_id\": \"GRP98999\",\n  \"insurance_provider_id\": \"insurance-provider-123\",\n  \"insurance_payer_id\": \"98999\",\n  \"insurance_name\": \"Blue Cross Anthem\",\n  \"subscriber_demographics\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"street_line_1\": \"123 Main Street\",\n    \"city\": \"Los Angeles\",\n    \"state\": \"CA\",\n    \"zip\": \"90001\",\n    \"sex\": \"F\",\n    \"dob\": \"1980-01-15\",\n    \"phone\": \"555-123-4567\"\n  },\n  \"relationship_to_subscriber\": \"self\",\n  \"insurance_policy_type\": \"PPO\",\n  \"insurance_sequence\": \"primary\",\n  \"plan_begin_date\": \"2026-01-01\",\n  \"plan_end_date\": \"2026-12-31\",\n  \"copayment\": 25,\n  \"telehealth_copayment\": 10,\n  \"include_inactive_patients\": false,\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ],\n  \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances/{emr_insurance_id}")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"member_id\": \"MEM123456789\",\n  \"group_id\": \"GRP98999\",\n  \"insurance_provider_id\": \"insurance-provider-123\",\n  \"insurance_payer_id\": \"98999\",\n  \"insurance_name\": \"Blue Cross Anthem\",\n  \"subscriber_demographics\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"street_line_1\": \"123 Main Street\",\n    \"city\": \"Los Angeles\",\n    \"state\": \"CA\",\n    \"zip\": \"90001\",\n    \"sex\": \"F\",\n    \"dob\": \"1980-01-15\",\n    \"phone\": \"555-123-4567\"\n  },\n  \"relationship_to_subscriber\": \"self\",\n  \"insurance_policy_type\": \"PPO\",\n  \"insurance_sequence\": \"primary\",\n  \"plan_begin_date\": \"2026-01-01\",\n  \"plan_end_date\": \"2026-12-31\",\n  \"copayment\": 25,\n  \"telehealth_copayment\": 10,\n  \"include_inactive_patients\": false,\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/patients/{patient_mrn}/insurances/{emr_insurance_id}")

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

request = Net::HTTP::Patch.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  \"member_id\": \"MEM123456789\",\n  \"group_id\": \"GRP98999\",\n  \"insurance_provider_id\": \"insurance-provider-123\",\n  \"insurance_payer_id\": \"98999\",\n  \"insurance_name\": \"Blue Cross Anthem\",\n  \"subscriber_demographics\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"street_line_1\": \"123 Main Street\",\n    \"city\": \"Los Angeles\",\n    \"state\": \"CA\",\n    \"zip\": \"90001\",\n    \"sex\": \"F\",\n    \"dob\": \"1980-01-15\",\n    \"phone\": \"555-123-4567\"\n  },\n  \"relationship_to_subscriber\": \"self\",\n  \"insurance_policy_type\": \"PPO\",\n  \"insurance_sequence\": \"primary\",\n  \"plan_begin_date\": \"2026-01-01\",\n  \"plan_end_date\": \"2026-12-31\",\n  \"copayment\": 25,\n  \"telehealth_copayment\": 10,\n  \"include_inactive_patients\": false,\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": "Patient insurance queued for processing",
  "patient_insurance_id": "d4e5f6a1b2c3478899aabbccddeeff00",
  "job_id": 12345
}

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

PATCH

patients

{patient_mrn}

insurances

{emr_insurance_id}

Update a patient insurance record

curl --request PATCH \
  --url https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances/{emr_insurance_id} \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "member_id": "MEM123456789",
  "group_id": "GRP98999",
  "insurance_provider_id": "insurance-provider-123",
  "insurance_payer_id": "98999",
  "insurance_name": "Blue Cross Anthem",
  "subscriber_demographics": {
    "first_name": "Jane",
    "last_name": "Doe",
    "street_line_1": "123 Main Street",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "sex": "F",
    "dob": "1980-01-15",
    "phone": "555-123-4567"
  },
  "relationship_to_subscriber": "self",
  "insurance_policy_type": "PPO",
  "insurance_sequence": "primary",
  "plan_begin_date": "2026-01-01",
  "plan_end_date": "2026-12-31",
  "copayment": 25,
  "telehealth_copayment": 10,
  "include_inactive_patients": false,
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ],
  "expires_at": "2027-06-15T14:30:00Z"
}
'

import requests

url = "https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances/{emr_insurance_id}"

payload = {
    "member_id": "MEM123456789",
    "group_id": "GRP98999",
    "insurance_provider_id": "insurance-provider-123",
    "insurance_payer_id": "98999",
    "insurance_name": "Blue Cross Anthem",
    "subscriber_demographics": {
        "first_name": "Jane",
        "last_name": "Doe",
        "street_line_1": "123 Main Street",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90001",
        "sex": "F",
        "dob": "1980-01-15",
        "phone": "555-123-4567"
    },
    "relationship_to_subscriber": "self",
    "insurance_policy_type": "PPO",
    "insurance_sequence": "primary",
    "plan_begin_date": "2026-01-01",
    "plan_end_date": "2026-12-31",
    "copayment": 25,
    "telehealth_copayment": 10,
    "include_inactive_patients": False,
    "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.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    member_id: 'MEM123456789',
    group_id: 'GRP98999',
    insurance_provider_id: 'insurance-provider-123',
    insurance_payer_id: '98999',
    insurance_name: 'Blue Cross Anthem',
    subscriber_demographics: {
      first_name: 'Jane',
      last_name: 'Doe',
      street_line_1: '123 Main Street',
      city: 'Los Angeles',
      state: 'CA',
      zip: '90001',
      sex: 'F',
      dob: '1980-01-15',
      phone: '555-123-4567'
    },
    relationship_to_subscriber: 'self',
    insurance_policy_type: 'PPO',
    insurance_sequence: 'primary',
    plan_begin_date: '2026-01-01',
    plan_end_date: '2026-12-31',
    copayment: 25,
    telehealth_copayment: 10,
    include_inactive_patients: false,
    callback_urls: ['https://example.com/webhooks/cobalt'],
    expires_at: '2027-06-15T14:30:00Z'
  })
};

fetch('https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances/{emr_insurance_id}', 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/patients/{patient_mrn}/insurances/{emr_insurance_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'member_id' => 'MEM123456789',
    'group_id' => 'GRP98999',
    'insurance_provider_id' => 'insurance-provider-123',
    'insurance_payer_id' => '98999',
    'insurance_name' => 'Blue Cross Anthem',
    'subscriber_demographics' => [
        'first_name' => 'Jane',
        'last_name' => 'Doe',
        'street_line_1' => '123 Main Street',
        'city' => 'Los Angeles',
        'state' => 'CA',
        'zip' => '90001',
        'sex' => 'F',
        'dob' => '1980-01-15',
        'phone' => '555-123-4567'
    ],
    'relationship_to_subscriber' => 'self',
    'insurance_policy_type' => 'PPO',
    'insurance_sequence' => 'primary',
    'plan_begin_date' => '2026-01-01',
    'plan_end_date' => '2026-12-31',
    'copayment' => 25,
    'telehealth_copayment' => 10,
    'include_inactive_patients' => false,
    '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/patients/{patient_mrn}/insurances/{emr_insurance_id}"

	payload := strings.NewReader("{\n  \"member_id\": \"MEM123456789\",\n  \"group_id\": \"GRP98999\",\n  \"insurance_provider_id\": \"insurance-provider-123\",\n  \"insurance_payer_id\": \"98999\",\n  \"insurance_name\": \"Blue Cross Anthem\",\n  \"subscriber_demographics\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"street_line_1\": \"123 Main Street\",\n    \"city\": \"Los Angeles\",\n    \"state\": \"CA\",\n    \"zip\": \"90001\",\n    \"sex\": \"F\",\n    \"dob\": \"1980-01-15\",\n    \"phone\": \"555-123-4567\"\n  },\n  \"relationship_to_subscriber\": \"self\",\n  \"insurance_policy_type\": \"PPO\",\n  \"insurance_sequence\": \"primary\",\n  \"plan_begin_date\": \"2026-01-01\",\n  \"plan_end_date\": \"2026-12-31\",\n  \"copayment\": 25,\n  \"telehealth_copayment\": 10,\n  \"include_inactive_patients\": false,\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ],\n  \"expires_at\": \"2027-06-15T14:30:00Z\"\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances/{emr_insurance_id}")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"member_id\": \"MEM123456789\",\n  \"group_id\": \"GRP98999\",\n  \"insurance_provider_id\": \"insurance-provider-123\",\n  \"insurance_payer_id\": \"98999\",\n  \"insurance_name\": \"Blue Cross Anthem\",\n  \"subscriber_demographics\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"street_line_1\": \"123 Main Street\",\n    \"city\": \"Los Angeles\",\n    \"state\": \"CA\",\n    \"zip\": \"90001\",\n    \"sex\": \"F\",\n    \"dob\": \"1980-01-15\",\n    \"phone\": \"555-123-4567\"\n  },\n  \"relationship_to_subscriber\": \"self\",\n  \"insurance_policy_type\": \"PPO\",\n  \"insurance_sequence\": \"primary\",\n  \"plan_begin_date\": \"2026-01-01\",\n  \"plan_end_date\": \"2026-12-31\",\n  \"copayment\": 25,\n  \"telehealth_copayment\": 10,\n  \"include_inactive_patients\": false,\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/patients/{patient_mrn}/insurances/{emr_insurance_id}")

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

request = Net::HTTP::Patch.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  \"member_id\": \"MEM123456789\",\n  \"group_id\": \"GRP98999\",\n  \"insurance_provider_id\": \"insurance-provider-123\",\n  \"insurance_payer_id\": \"98999\",\n  \"insurance_name\": \"Blue Cross Anthem\",\n  \"subscriber_demographics\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"street_line_1\": \"123 Main Street\",\n    \"city\": \"Los Angeles\",\n    \"state\": \"CA\",\n    \"zip\": \"90001\",\n    \"sex\": \"F\",\n    \"dob\": \"1980-01-15\",\n    \"phone\": \"555-123-4567\"\n  },\n  \"relationship_to_subscriber\": \"self\",\n  \"insurance_policy_type\": \"PPO\",\n  \"insurance_sequence\": \"primary\",\n  \"plan_begin_date\": \"2026-01-01\",\n  \"plan_end_date\": \"2026-12-31\",\n  \"copayment\": 25,\n  \"telehealth_copayment\": 10,\n  \"include_inactive_patients\": false,\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": "Patient insurance queued for processing",
  "patient_insurance_id": "d4e5f6a1b2c3478899aabbccddeeff00",
  "job_id": 12345
}

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

This endpoint queues an asynchronous update for an existing patient insurance record.

Ending / cancelling coverage: there is no delete endpoint for insurance records. To end coverage, PATCH the record with a plan_end_date.

Identifying The Insurance To Update

Use the EMR insurance record ID. You can get it from either:

POST /v1/patients/fetch with include: ["insurances"]
the emr_insurance_id returned in a prior patient.insurance.added or patient.insurance.updated webhook

In live fetch responses, the update target is returned as insurances[].emr_insurance_id.

Provider Resolution

The API supports the same insurance provider resolution options as insurance create:

insurance_provider_id
insurance_name + insurance_payer_id
insurance_name

insurance_payer_id alone is not supported. If you request a carrier change, the resolved insurance provider must have an EMR ehrId configured or the request will be rejected.

Validation Rules

All request body fields are optional. Omitted fields are preserved from the current EMR insurance record.
emr_insurance_id is required in the URL path.
If you send subscriber_demographics, it must include first_name and last_name.
If relationship_to_subscriber is a non-self value such as spouse, child, or other, subscriber_demographics.first_name and subscriber_demographics.last_name are required.
plan_begin_date, when provided, must be in YYYY-MM-DD format.
plan_end_date, when provided, must be in YYYY-MM-DD format. When omitted, the current coverage end date is preserved (not cleared).

Discover The Record ID First

curl -X POST https://api.usecobalt.com/v1/patients/fetch \
  -H "Content-Type: application/json" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -d '{
    "mrn": "MRN123456",
    "search_by": "mrn",
    "include": ["insurances"]
  }'

Example insurance entry from the live-fetch webhook payload:

{
  "emr_insurance_id": "51638",
  "priority": 1,
  "insurance_ehr_id": "733",
  "insurance_name": "Alignment Health Plan(P)",
  "insurance_subscriber_number": "MEM-POSTMAN-001",
  "group_id": "GRP-POSTMAN-001",
  "plan_begin_date": "2026-07-01",
  "plan_end_date": "2027-06-30",
  "copayment": "10.00",
  "relationship_to_subscriber": "spouse",
  "guarantor_id": "90688",
  "is_guarantor_patient": false
}

Example Requests

Update A Few Insurance Fields

curl -X PATCH https://api.usecobalt.com/v1/patients/MRN123456/insurances/51638 \
  -H "Content-Type: application/json" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -d '{
    "member_id": "MEM123456789",
    "group_id": "GRP98999",
    "plan_begin_date": "2025-01-01",
    "copayment": 25
  }'

Update Coverage Dates

curl -X PATCH https://api.usecobalt.com/v1/patients/MRN123456/insurances/51638 \
  -H "Content-Type: application/json" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -d '{
    "plan_begin_date": "2026-01-01",
    "plan_end_date": "2026-12-31"
  }'

Change To A Non-Self Subscriber

curl -X PATCH https://api.usecobalt.com/v1/patients/MRN123456/insurances/51638 \
  -H "Content-Type: application/json" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -d '{
    "relationship_to_subscriber": "spouse",
    "subscriber_demographics": {
      "first_name": "Jane",
      "last_name": "Doe",
      "dob": "1985-04-12",
      "phone": "5551234567",
      "sex": "F"
    }
  }'

Change The Carrier

curl -X PATCH https://api.usecobalt.com/v1/patients/MRN123456/insurances/51638 \
  -H "Content-Type: application/json" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -d '{
    "insurance_name": "ACE Medicare Supplement",
    "insurance_payer_id": "14367"
  }'

Example Response

{
  "success": true,
  "message": "Insurance update queued successfully. Processing will begin shortly.",
  "patient_insurance_id": "xyz789abc123",
  "job_id": 12345
}

Webhook Events

Success Event (patient.insurance.updated)

{
  "id": "evt_abc123def456",
  "access_token_reference_id": "your_reference_id",
  "object": "event",
  "created": "2025-01-15T10:30:00.000Z",
  "type": "patient.insurance.updated",
  "job_id": "12345",
  "data": {
    "patient_insurance_id": "xyz789abc123",
    "patient_mrn": "MRN123456",
    "member_id": "MEM123456789",
    "group_id": "GRP98999",
    "plan_begin_date": "2025-01-01",
    "plan_end_date": "2025-12-31",
    "copayment": 25,
    "priority": 1,
    "relationship_to_subscriber": "spouse",
    "emr_insurance_id": "51638"
  }
}

Failure Event (patient.insurance.failed)

{
  "id": "evt_xyz789abc123",
  "access_token_reference_id": "your_reference_id",
  "object": "event",
  "created": "2025-01-15T10:30:00.000Z",
  "type": "patient.insurance.failed",
  "job_id": "12345",
  "data": {
    "patient_insurance_id": "xyz789abc123",
    "patient_mrn": "MRN123456",
    "failure_reason": "No existing insurance found with emr_insurance_id 51638 for patient MRN123456"
  }
}

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Path Parameters

patient_mrn

string

required

Patient MRN.

Example:

"12345"

emr_insurance_id

string

required

EMR insurance record ID. Returned as emr_insurance_id in patient live fetch and create/update success webhooks.

Example:

"51638"

Body

application/json

member_id

string

Insurance member / subscriber ID.

Example:

"MEM123456789"

group_id

string

Insurance group number.

Example:

"GRP98999"

insurance_provider_id

string

Cobalt insurance provider ID (one insurance identifier). Use GET /v1/insurance-providers to retrieve valid IDs.

Example:

"insurance-provider-123"

insurance_payer_id

string

Insurance payer ID, used to disambiguate insurance_name.

Example:

"98999"

insurance_name

string

Insurance provider name (one insurance identifier).

Example:

"Blue Cross Anthem"

subscriber_demographics

object

Policy holder demographics.

Show child attributes

relationship_to_subscriber

string

Patient relationship to the policy holder.

Example:

"self"

insurance_policy_type

string

Insurance policy type / coverage category. Accepted, but no EMR uses it, so it has no effect.

Example:

"PPO"

insurance_sequence

string

Coverage order (e.g. primary / secondary). Sent to the EMR by Credible; for every EMR, GET /v1/patients uses it to pick which active insurance to report.

Example:

"primary"

plan_begin_date

string<date>

Plan begin date (YYYY-MM-DD).

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-01-01"

plan_end_date

string<date>

Plan end date (YYYY-MM-DD). Omit for open-ended coverage.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-12-31"

copayment

number

Copayment amount. For Athena this is the Office Visit copay. Athena requires copayment and/or telehealth_copayment.

Required range: x >= 0

Example:

25

telehealth_copayment

number

Telehealth copayment amount (Athena). Athena requires copayment and/or telehealth_copayment.

Required range: x >= 0

Example:

10

include_inactive_patients

boolean

Also match a patient chart that is inactive in the EMR when looking up the patient. Defaults to false (active charts only).

Example:

false

callback_urls

string[]

URLs to receive the completion webhook, 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

Operation queued for processing

success

boolean

required

Example:

true

message

string

required

Example:

"Patient insurance queued for processing"

patient_insurance_id

string

required

Example:

"d4e5f6a1b2c3478899aabbccddeeff00"

job_id

integer

required

Example:

12345

​Identifying The Insurance To Update

​Provider Resolution

​Validation Rules

​Discover The Record ID First

​Example Requests

​Update A Few Insurance Fields

​Update Coverage Dates

​Change To A Non-Self Subscriber

​Change The Carrier

​Example Response

​Webhook Events

​Success Event (patient.insurance.updated)

​Failure Event (patient.insurance.failed)

Authorizations

Path Parameters

Body

Response

Identifying The Insurance To Update

Provider Resolution

Validation Rules

Discover The Record ID First

Example Requests

Update A Few Insurance Fields

Update Coverage Dates

Change To A Non-Self Subscriber

Change The Carrier

Example Response

Webhook Events

Success Event (patient.insurance.updated)

Failure Event (patient.insurance.failed)