Attach insurance to an existing patient

curl --request POST \
  --url https://api.maxcare.ai/v2/patients/{id}/insurance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "payerName": "BCBS of Michigan",
  "memberId": "XYZ123456",
  "groupNumber": "0009",
  "subscriberRelationship": "SELF",
  "subscriberFirstName": "Robert",
  "subscriberLastName": "Doe",
  "subscriberDateOfBirth": "1968-03-14",
  "subscriberSex": "M",
  "subscriberAddressSameAsPatient": true,
  "planName": "PPO Gold"
}
'

import requests

url = "https://api.maxcare.ai/v2/patients/{id}/insurance"

payload = {
    "payerName": "BCBS of Michigan",
    "memberId": "XYZ123456",
    "groupNumber": "0009",
    "subscriberRelationship": "SELF",
    "subscriberFirstName": "Robert",
    "subscriberLastName": "Doe",
    "subscriberDateOfBirth": "1968-03-14",
    "subscriberSex": "M",
    "subscriberAddressSameAsPatient": True,
    "planName": "PPO Gold"
}
headers = {
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Organization-Id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payerName: 'BCBS of Michigan',
    memberId: 'XYZ123456',
    groupNumber: '0009',
    subscriberRelationship: 'SELF',
    subscriberFirstName: 'Robert',
    subscriberLastName: 'Doe',
    subscriberDateOfBirth: '1968-03-14',
    subscriberSex: 'M',
    subscriberAddressSameAsPatient: true,
    planName: 'PPO Gold'
  })
};

fetch('https://api.maxcare.ai/v2/patients/{id}/insurance', 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.maxcare.ai/v2/patients/{id}/insurance",
  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([
    'payerName' => 'BCBS of Michigan',
    'memberId' => 'XYZ123456',
    'groupNumber' => '0009',
    'subscriberRelationship' => 'SELF',
    'subscriberFirstName' => 'Robert',
    'subscriberLastName' => 'Doe',
    'subscriberDateOfBirth' => '1968-03-14',
    'subscriberSex' => 'M',
    'subscriberAddressSameAsPatient' => true,
    'planName' => 'PPO Gold'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Organization-Id: <x-organization-id>"
  ],
]);

$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.maxcare.ai/v2/patients/{id}/insurance"

	payload := strings.NewReader("{\n  \"payerName\": \"BCBS of Michigan\",\n  \"memberId\": \"XYZ123456\",\n  \"groupNumber\": \"0009\",\n  \"subscriberRelationship\": \"SELF\",\n  \"subscriberFirstName\": \"Robert\",\n  \"subscriberLastName\": \"Doe\",\n  \"subscriberDateOfBirth\": \"1968-03-14\",\n  \"subscriberSex\": \"M\",\n  \"subscriberAddressSameAsPatient\": true,\n  \"planName\": \"PPO Gold\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	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.maxcare.ai/v2/patients/{id}/insurance")
  .header("X-Organization-Id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payerName\": \"BCBS of Michigan\",\n  \"memberId\": \"XYZ123456\",\n  \"groupNumber\": \"0009\",\n  \"subscriberRelationship\": \"SELF\",\n  \"subscriberFirstName\": \"Robert\",\n  \"subscriberLastName\": \"Doe\",\n  \"subscriberDateOfBirth\": \"1968-03-14\",\n  \"subscriberSex\": \"M\",\n  \"subscriberAddressSameAsPatient\": true,\n  \"planName\": \"PPO Gold\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v2/patients/{id}/insurance")

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

request = Net::HTTP::Post.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payerName\": \"BCBS of Michigan\",\n  \"memberId\": \"XYZ123456\",\n  \"groupNumber\": \"0009\",\n  \"subscriberRelationship\": \"SELF\",\n  \"subscriberFirstName\": \"Robert\",\n  \"subscriberLastName\": \"Doe\",\n  \"subscriberDateOfBirth\": \"1968-03-14\",\n  \"subscriberSex\": \"M\",\n  \"subscriberAddressSameAsPatient\": true,\n  \"planName\": \"PPO Gold\"\n}"

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

{
  "code": "success",
  "data": {
    "patientId": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
    "coverageOrder": 1,
    "payerName": "BCBS of Michigan"
  }
}

{
  "code": "bad_request",
  "message": "'id' must be a valid UUID",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "forbidden",
  "message": "Insufficient scope",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "not_found",
  "message": "Resource not found",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unexpected_integration_error",
  "message": "EHR sync failed",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "server_unresponsive",
  "message": "EHR integration is not available for this note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Patients

Attach insurance to an existing patient

Adds coverage to a chart that already exists — the returning-patient counterpart to the insurance block on POST /patients. ADDITIVE: the EHR keeps existing policies, so this never replaces coverage and conflictPolicy does not apply. Coverage is written as primary; secondary coverage remains an intake concern. A non-self policy REQUIRES the subscriber* fields and is rejected with subscriber_required without them. Send an Idempotency-Key header to make a retry safe: it is honoured for 24 hours per app+organization, a repeat of the SAME request replays the original result, and a key reused for a DIFFERENT request is refused with 409. The guarantee fails closed — if the idempotency store is unreachable the request is refused with 503 idempotency_unavailable rather than proceeding unguarded.

POST

patients

{id}

insurance

Attach insurance to an existing patient

curl --request POST \
  --url https://api.maxcare.ai/v2/patients/{id}/insurance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "payerName": "BCBS of Michigan",
  "memberId": "XYZ123456",
  "groupNumber": "0009",
  "subscriberRelationship": "SELF",
  "subscriberFirstName": "Robert",
  "subscriberLastName": "Doe",
  "subscriberDateOfBirth": "1968-03-14",
  "subscriberSex": "M",
  "subscriberAddressSameAsPatient": true,
  "planName": "PPO Gold"
}
'

import requests

url = "https://api.maxcare.ai/v2/patients/{id}/insurance"

payload = {
    "payerName": "BCBS of Michigan",
    "memberId": "XYZ123456",
    "groupNumber": "0009",
    "subscriberRelationship": "SELF",
    "subscriberFirstName": "Robert",
    "subscriberLastName": "Doe",
    "subscriberDateOfBirth": "1968-03-14",
    "subscriberSex": "M",
    "subscriberAddressSameAsPatient": True,
    "planName": "PPO Gold"
}
headers = {
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Organization-Id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payerName: 'BCBS of Michigan',
    memberId: 'XYZ123456',
    groupNumber: '0009',
    subscriberRelationship: 'SELF',
    subscriberFirstName: 'Robert',
    subscriberLastName: 'Doe',
    subscriberDateOfBirth: '1968-03-14',
    subscriberSex: 'M',
    subscriberAddressSameAsPatient: true,
    planName: 'PPO Gold'
  })
};

fetch('https://api.maxcare.ai/v2/patients/{id}/insurance', 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.maxcare.ai/v2/patients/{id}/insurance",
  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([
    'payerName' => 'BCBS of Michigan',
    'memberId' => 'XYZ123456',
    'groupNumber' => '0009',
    'subscriberRelationship' => 'SELF',
    'subscriberFirstName' => 'Robert',
    'subscriberLastName' => 'Doe',
    'subscriberDateOfBirth' => '1968-03-14',
    'subscriberSex' => 'M',
    'subscriberAddressSameAsPatient' => true,
    'planName' => 'PPO Gold'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Organization-Id: <x-organization-id>"
  ],
]);

$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.maxcare.ai/v2/patients/{id}/insurance"

	payload := strings.NewReader("{\n  \"payerName\": \"BCBS of Michigan\",\n  \"memberId\": \"XYZ123456\",\n  \"groupNumber\": \"0009\",\n  \"subscriberRelationship\": \"SELF\",\n  \"subscriberFirstName\": \"Robert\",\n  \"subscriberLastName\": \"Doe\",\n  \"subscriberDateOfBirth\": \"1968-03-14\",\n  \"subscriberSex\": \"M\",\n  \"subscriberAddressSameAsPatient\": true,\n  \"planName\": \"PPO Gold\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	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.maxcare.ai/v2/patients/{id}/insurance")
  .header("X-Organization-Id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payerName\": \"BCBS of Michigan\",\n  \"memberId\": \"XYZ123456\",\n  \"groupNumber\": \"0009\",\n  \"subscriberRelationship\": \"SELF\",\n  \"subscriberFirstName\": \"Robert\",\n  \"subscriberLastName\": \"Doe\",\n  \"subscriberDateOfBirth\": \"1968-03-14\",\n  \"subscriberSex\": \"M\",\n  \"subscriberAddressSameAsPatient\": true,\n  \"planName\": \"PPO Gold\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v2/patients/{id}/insurance")

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

request = Net::HTTP::Post.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payerName\": \"BCBS of Michigan\",\n  \"memberId\": \"XYZ123456\",\n  \"groupNumber\": \"0009\",\n  \"subscriberRelationship\": \"SELF\",\n  \"subscriberFirstName\": \"Robert\",\n  \"subscriberLastName\": \"Doe\",\n  \"subscriberDateOfBirth\": \"1968-03-14\",\n  \"subscriberSex\": \"M\",\n  \"subscriberAddressSameAsPatient\": true,\n  \"planName\": \"PPO Gold\"\n}"

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

{
  "code": "success",
  "data": {
    "patientId": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
    "coverageOrder": 1,
    "payerName": "BCBS of Michigan"
  }
}

{
  "code": "bad_request",
  "message": "'id' must be a valid UUID",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "forbidden",
  "message": "Insufficient scope",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "not_found",
  "message": "Resource not found",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unexpected_integration_error",
  "message": "EHR sync failed",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "server_unresponsive",
  "message": "EHR integration is not available for this note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Authorizations

Authorization

string

header

required

Marketplace API key

Headers

idempotency-key

string

Client-generated key protecting retries for 24 hours

X-Organization-Id

string

required

Target clinic organization ID

Path Parameters

string

required

Patient ID

Body

application/json

payerName

string

required

Example:

"BCBS of Michigan"

memberId

string

required

Example:

"XYZ123456"

groupNumber

string

Example:

"0009"

subscriberRelationship

string

The policyholder's relationship to the patient. SELF (the default) means the patient is the policyholder. Anything else — SPOUSE, CHILD, … — REQUIRES the subscriber* fields below; without them the request is rejected with subscriber_required rather than writing a policy whose policyholder is unknown.

Example:

"SELF"

subscriberFirstName

string

Policyholder's first name. Required when subscriberRelationship is not SELF.

Example:

"Robert"

subscriberLastName

string

Policyholder's last name. Required when subscriberRelationship is not SELF.

Example:

"Doe"

subscriberDateOfBirth

string

Policyholder's date of birth, YYYY-MM-DD. Required when subscriberRelationship is not SELF — a claim identifies the subscriber by name AND date of birth, so a name alone still sends the biller back to the patient.

Example:

"1968-03-14"

subscriberSex

enum<string>

Policyholder's sex, as the payer knows it. A professional claim's 2010BA loop carries the subscriber's DMG demographics — date of birth AND gender — so omitting it leaves a correctable rejection on the table. NOT required: unlike name and date of birth, a missing gender does not make the policyholder unidentifiable, so it is never a reason to refuse the write.

Available options:

M,

F,

U

Example:

"M"

subscriberAddress

object

Policyholder's address, for the claim's 2010BA N3/N4 segments. Omit and set subscriberAddressSameAsPatient instead when the policyholder lives with the patient — the common case for a spouse or dependant, and the one ModMed models natively.

Show child attributes

subscriberAddressSameAsPatient

boolean

true when the policyholder lives at the patient's address. Maps to ModMed's own policyHolderAddressSameAsPatients, so the EHR resolves the address itself rather than us copying it and creating a second copy that can drift. Mutually exclusive with subscriberAddress; supplying both is rejected.

Example:

true

planName

string

Plan name as printed on the card (e.g. PPO Gold). Previously always written as null; supply it when the card shows it.

Example:

"PPO Gold"

Response

Success

code

string

required

Response code

Example:

"success"

data

object

required

Show child attributes