> ## Documentation Index > Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi-v4.json post /patients/{id}/insurance openapi: 3.0.0 info: title: Max AI Public API description: API for third-party marketplace apps version: '4.0' contact: {} servers: - url: https://api.maxcare.ai/v4 security: [] tags: [] paths: /patients/{id}/insurance: post: tags: - Patients summary: Attach insurance to an existing patient description: >- 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. operationId: PatientsPublicController_addPatientInsurance parameters: - name: id required: true in: path description: Patient ID schema: type: string - name: idempotency-key required: false in: header description: Client-generated key protecting retries for 24 hours schema: type: string - name: X-Organization-Id in: header required: true schema: type: string description: Target clinic organization ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PatientInsuranceBody' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AddPatientInsuranceSuccessResponse' '400': description: Missing or invalid request parameter content: application/json: schema: $ref: '#/components/schemas/PublicApiBadRequestResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/PublicApiUnauthorizedResponse' '403': description: Insufficient scope content: application/json: schema: $ref: '#/components/schemas/PublicApiForbiddenResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/PublicApiNotFoundResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/PublicApiRateLimitResponse' '502': description: EHR sync failed content: application/json: schema: $ref: '#/components/schemas/PublicApiBadGatewayResponse' '503': description: EHR integration unavailable content: application/json: schema: $ref: '#/components/schemas/PublicApiServiceUnavailableResponse' security: - api-key: [] components: schemas: PatientInsuranceBody: type: object properties: payerName: type: string example: BCBS of Michigan memberId: type: string example: XYZ123456 groupNumber: type: string example: '0009' subscriberRelationship: type: string description: >- 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: type: string description: >- Policyholder's first name. Required when `subscriberRelationship` is not `SELF`. example: Robert subscriberLastName: type: string description: >- Policyholder's last name. Required when `subscriberRelationship` is not `SELF`. example: Doe subscriberDateOfBirth: type: string description: >- 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: type: string description: >- 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. enum: - M - F - U example: M subscriberAddress: description: >- 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. allOf: - $ref: '#/components/schemas/PatientAddressBody' subscriberAddressSameAsPatient: type: boolean description: >- `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: type: string description: >- 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 required: - payerName - memberId AddPatientInsuranceSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/AddPatientInsuranceData' required: - code - data PublicApiBadRequestResponse: type: object properties: code: type: string description: Error code example: bad_request message: type: string description: Human-readable error message example: '''id'' must be a valid UUID' trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiUnauthorizedResponse: type: object properties: code: type: string description: Error code example: unauthorized message: type: string description: Human-readable error message example: Invalid or missing API key trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiForbiddenResponse: type: object properties: code: type: string description: Error code example: forbidden message: type: string description: Human-readable error message example: Insufficient scope trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiNotFoundResponse: type: object properties: code: type: string description: Error code example: not_found message: type: string description: Human-readable error message example: Resource not found trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiRateLimitResponse: type: object properties: code: type: string description: Error code example: rate_limit_exceeded message: type: string description: Human-readable error message example: Rate limit exceeded. Maximum 1000 requests per 60 seconds. trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiBadGatewayResponse: type: object properties: code: type: string description: Error code example: unexpected_integration_error message: type: string description: Human-readable error message example: EHR sync failed trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiServiceUnavailableResponse: type: object properties: code: type: string description: Error code example: server_unresponsive message: type: string description: Human-readable error message example: EHR integration is not available for this note trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PatientAddressBody: type: object properties: line1: type: string example: 1200 Miller Rd line2: type: string example: Apt 4 city: type: string example: Flint state: type: string description: >- Two-letter state code. The adapters translate to each vendor's form (EZDerm `FLORIDA`, ModMed `FL`). example: MI zip: type: string example: '48507' country: type: string example: US required: - line1 - city - state - zip AddPatientInsuranceData: type: object properties: patientId: type: string description: The patient the coverage was attached to example: pat_c56103bcd39c46d39f3138dd2b5e05f6 coverageOrder: type: number description: Coverage order written — 1 is primary example: 1 payerName: type: string description: Payer name as resolved by the EHR example: BCBS of Michigan required: - patientId - coverageOrder - payerName securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ````