Skip to main content
POST
Attach insurance with an exact payer

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

​
id
string
required

Patient ID

Body

application/json
​
memberId
string
required

Member id as printed on the card. Required and non-blank: it decides whether the coverage is already on the chart.

Required string length: 1 - 100
Example:

"XYZ123456"

​
payerId
string
required

Max AI payer id from GET /payers — the exact practice payer to attach. Resolved within the patient's own EHR instance and written by its EHR id, never by a name search. A payer from another organization or instance, an inactive payer, or one with no EHR id is refused with 422 payer_not_writable.

Example:

"8b9c0a52-3f1e-4c2a-9d7b-2a6f3e1c4b5d"

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

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

​
policyType
enum<string>

Policy type, using ModMed's own names. Applies only to a policy this request adds; omitted, it is filed as COMMERCIAL_OTHER. A policy already on the chart is never edited here; change its type with PATCH /patients/{patientId}/insurance-policies/{policyId}, using the policy's id from GET /insurance-policies (not this response's EHR policyId); a policy added here is listed there after the next EHR sync. Ignored on EHRs without a policy type (see GET /payers/capabilities).

Available options:
MEDICARE,
MEDICARE_ADVANTAGE,
MEDICAID,
CHIP,
TRICARE,
CHAMPVA,
GOVERNMENT_OTHER,
COMMERCIAL_OTHER,
HMO,
PPO,
EPO,
POS,
GHP,
IPA,
ACA_EXCHANGE
Example:

"MEDICARE"

​
coverageOrder
enum<number>

Rank the new policy must take: 1 primary, 2 secondary. When sent, the policy is written at exactly that rank or refused with nothing written: 409 coverage_rank_taken when another policy holds it, 409 coverage_rank_out_of_order when a lower rank is still free (write the primary first). Omitted, the EHR files the policy at its next free rank.

Available options:
1,
2
Example:

2

Response

Success

​
code
string
required

Response code

Example:

"success"

​
data
object
required