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,
  "callback_urls": [
    "<string>"
  ]
}
'

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,
    "callback_urls": ["<string>"]
}
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,
    callback_urls: ['<string>']
  })
};

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,
    '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/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  \"callback_urls\": [\n    \"<string>\"\n  ]\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  \"callback_urls\": [\n    \"<string>\"\n  ]\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  \"callback_urls\": [\n    \"<string>\"\n  ]\n}"

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

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

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

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

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

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

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,
  "callback_urls": [
    "<string>"
  ]
}
'

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,
    "callback_urls": ["<string>"]
}
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,
    callback_urls: ['<string>']
  })
};

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,
    '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/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  \"callback_urls\": [\n    \"<string>\"\n  ]\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  \"callback_urls\": [\n    \"<string>\"\n  ]\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  \"callback_urls\": [\n    \"<string>\"\n  ]\n}"

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

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

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

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

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

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

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

Insurance updates are currently supported for eClinicalWorks only.

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 for eClinicalWorks, the resolved insurance provider must have an eCW 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.
For eClinicalWorks, if you send subscriber_demographics, it must include first_name and last_name.
For eClinicalWorks, 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.

emr_insurance_id

string

required

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

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.

Example:

"PPO"

insurance_sequence

string

Coverage order (e.g. primary / secondary).

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.

Required range: x >= 0

Example:

25

callback_urls

string[]

URLs to receive the completion webhook, in addition to the account webhook.

Response

Operation queued for processing

success

boolean

required

message

string

required

patient_insurance_id

string

required

job_id

integer

required

​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)