> ## 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 with an exact payer > Attaches coverage using the exact practice payer picked from `GET /payers` (`payerId`), instead of searching the EHR's payer list by name and taking the first hit. The payer is written by its EHR id; there is never a name-search fallback. Refused with 422 `payer_not_writable` before anything is written when the payer is not in this organization and the patient's EHR instance (`data.reason: not_found_in_instance`), is inactive (`inactive`), has no EHR id (`no_integration_id`), or no longer exists in the EHR (`ehr_payer_missing`). Refused with 422 `coverage_ranks_full` when every coverage rank on the chart is taken (nothing written; staff must archive a policy in the EHR, so retrying will not help). Send `coverageOrder` (1 primary, 2 secondary) to require that rank: refused with 409 `coverage_rank_taken` when another policy holds it, or 409 `coverage_rank_out_of_order` when a lower rank is still free; nothing is written either way. Without it the EHR files the policy at its next free rank. `coverageOrder` is part of the request, so reusing an `Idempotency-Key` with a different rank is refused. If the chart already has this payer with the same member id, nothing is written and `alreadyOnChart` is true: the response describes that policy as the EHR holds it, and any change to it is made in the EHR. Otherwise a new policy is added. The response is built from the EHR's own copy of the policy, read back after the write, so `payerId` confirms the payer the EHR holds — if that read-back does not confirm it the request fails with 409 `ehr_write_uncertain`. A server without this endpoint answers 404 without writing, so a client never silently falls back to a name search during a deploy. Same `Idempotency-Key` contract as `POST /patients/{id}/insurance`. ## OpenAPI ````yaml /openapi-v4.json post /patients/{id}/insurance:exact 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:exact: post: tags: - Patients summary: Attach insurance with an exact payer description: >- Attaches coverage using the exact practice payer picked from `GET /payers` (`payerId`), instead of searching the EHR's payer list by name and taking the first hit. The payer is written by its EHR id; there is never a name-search fallback. Refused with 422 `payer_not_writable` before anything is written when the payer is not in this organization and the patient's EHR instance (`data.reason: not_found_in_instance`), is inactive (`inactive`), has no EHR id (`no_integration_id`), or no longer exists in the EHR (`ehr_payer_missing`). Refused with 422 `coverage_ranks_full` when every coverage rank on the chart is taken (nothing written; staff must archive a policy in the EHR, so retrying will not help). Send `coverageOrder` (1 primary, 2 secondary) to require that rank: refused with 409 `coverage_rank_taken` when another policy holds it, or 409 `coverage_rank_out_of_order` when a lower rank is still free; nothing is written either way. Without it the EHR files the policy at its next free rank. `coverageOrder` is part of the request, so reusing an `Idempotency-Key` with a different rank is refused. If the chart already has this payer with the same member id, nothing is written and `alreadyOnChart` is true: the response describes that policy as the EHR holds it, and any change to it is made in the EHR. Otherwise a new policy is added. The response is built from the EHR's own copy of the policy, read back after the write, so `payerId` confirms the payer the EHR holds — if that read-back does not confirm it the request fails with 409 `ehr_write_uncertain`. A server without this endpoint answers 404 without writing, so a client never silently falls back to a name search during a deploy. Same `Idempotency-Key` contract as `POST /patients/{id}/insurance`. operationId: PatientsPublicController_addPatientInsuranceExact 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/ExactPatientInsuranceBody' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ExactPatientInsuranceSuccessResponse' '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' '409': description: Resource conflict (e.g. editing a signed note) content: application/json: schema: $ref: '#/components/schemas/PublicApiConflictResponse' '422': description: Request refused by the EHR's state (named `code`) content: application/json: schema: $ref: '#/components/schemas/PublicApiUnprocessableResponse' '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: ExactPatientInsuranceBody: type: object properties: 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 memberId: type: string description: >- Member id as printed on the card. Required and non-blank: it decides whether the coverage is already on the chart. example: XYZ123456 minLength: 1 maxLength: 100 payerId: type: string description: >- 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 policyType: type: string description: >- 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`). enum: - MEDICARE - MEDICARE_ADVANTAGE - MEDICAID - CHIP - TRICARE - CHAMPVA - GOVERNMENT_OTHER - COMMERCIAL_OTHER - HMO - PPO - EPO - POS - GHP - IPA - ACA_EXCHANGE example: MEDICARE coverageOrder: type: number description: >- 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. enum: - 1 - 2 example: 2 required: - memberId - payerId ExactPatientInsuranceSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/ExactPatientInsuranceData' 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 PublicApiConflictResponse: type: object properties: code: type: string description: Error code example: conflict message: type: string description: Human-readable error message example: Cannot edit a signed note trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiUnprocessableResponse: type: object properties: code: type: string description: Error code example: controlled_substance_unsupported message: type: string description: Human-readable error message example: Controlled substances cannot be prescribed through the API data: type: object description: Condition-specific detail, when the code defines any 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 ExactPatientInsuranceData: type: object properties: patientId: type: string description: The patient the coverage was attached to example: pat_c56103bcd39c46d39f3138dd2b5e05f6 coverageOrder: type: number description: >- Coverage order of the policy as the EHR holds it, read back after the write — 1 is primary example: 1 payerId: type: string description: >- The Max AI payer id now on the policy. Returned only after the EHR's own copy of the policy was read back and carries this payer, so it is what the EHR holds, not an echo of the request. example: 8b9c0a52-3f1e-4c2a-9d7b-2a6f3e1c4b5d payerName: type: string description: The payer's name in the practice's payer list example: BCBS of Michigan policyId: type: string description: The EHR's id for the policy example: '813407' alreadyOnChart: type: boolean description: >- True when this payer and member id were already on the chart: nothing was written, and the other fields describe that existing policy. example: false policyType: type: string nullable: true description: >- The policy type the EHR holds after the write; null when the EHR has none example: MEDICARE required: - patientId - coverageOrder - payerId - payerName - policyId - alreadyOnChart - policyType securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.