> ## 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. # Merge this chart into another > IRREVERSIBLE. Merges the path patient (source) into `intoPatientId` in the EHR: EMA copies the source's clinical data into the target and archives the source. Returns 202 with a merge to poll at `GET /v4/ehr/patient-merges/{id}` until `completed` or `failed`; `patient.merged` fires on completion. Refusals answer at once and merge nothing: 409 `merge_blocked` (with the EHR's `blockers`), `merge_instance_mismatch`, `patient_already_merged`, `merge_in_progress`, `patient_not_in_ehr`; 400 `merge_same_patient`; 403 `ehr_permission_missing`; 501 `capability_unsupported`. 409 `ehr_write_uncertain` with `mergeId` when the merge was sent and the EHR never answered: poll it, never resend. ## OpenAPI ````yaml /openapi-v4.json post /ehr/patients/{patientId}/merge 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: /ehr/patients/{patientId}/merge: post: tags: - Patient merges summary: Merge this chart into another description: >- IRREVERSIBLE. Merges the path patient (source) into `intoPatientId` in the EHR: EMA copies the source's clinical data into the target and archives the source. Returns 202 with a merge to poll at `GET /v4/ehr/patient-merges/{id}` until `completed` or `failed`; `patient.merged` fires on completion. Refusals answer at once and merge nothing: 409 `merge_blocked` (with the EHR's `blockers`), `merge_instance_mismatch`, `patient_already_merged`, `merge_in_progress`, `patient_not_in_ehr`; 400 `merge_same_patient`; 403 `ehr_permission_missing`; 501 `capability_unsupported`. 409 `ehr_write_uncertain` with `mergeId` when the merge was sent and the EHR never answered: poll it, never resend. operationId: PatientMergesPublicController_merge parameters: - name: patientId required: true in: path schema: type: string - name: idempotency-key required: true in: header description: >- Required. A retry with the same key and body returns the same merge; never merges twice. 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/CreatePatientMergeBody' responses: '202': description: Accepted — queued for background processing content: application/json: schema: $ref: '#/components/schemas/PatientMergeSuccessResponse' '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' '501': description: >- This organization's EHR does not support the capability (`capability_unsupported`) content: application/json: schema: $ref: '#/components/schemas/PublicApiNotImplementedResponse' '502': description: EHR sync failed content: application/json: schema: $ref: '#/components/schemas/PublicApiBadGatewayResponse' security: - api-key: [] components: schemas: CreatePatientMergeBody: type: object properties: intoPatientId: type: string description: >- The surviving chart. Same organization and same EHR instance as the path patient. example: pat_c56103bcd39c46d39f3138dd2b5e05f6 acknowledgeWarnings: type: boolean default: false description: >- Merge even though the EHR warned about the pair (e.g. differing first names), after staff confirmed both charts are the same person. Without it such a merge answers 409 `merge_needs_confirmation`. Blocks on either chart (balances, open bills) still refuse. required: - intoPatientId PatientMergeSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/ExternalPatientMergeResponse' 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 PublicApiNotImplementedResponse: type: object properties: code: type: string description: Error code example: capability_unsupported message: type: string description: Human-readable error message example: This organization's EHR has no appointment finder. 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 ExternalPatientMergeResponse: type: object properties: id: type: string example: pmg_0b6f1c1e8d2a4f7e9a3b5c7d9e1f2a3b status: type: string enum: - queued - running - completed - failed - uncertain description: >- `queued` → `running` (the EHR accepted the merge and is moving data) → `completed` | `failed`. `uncertain`: the merge was sent but the EHR never answered; it settles to `completed` or `failed` without being sent again. patientId: type: string description: The chart merged away; archived in the EHR once completed. intoPatientId: type: string description: The surviving chart. errorCode: type: string nullable: true description: >- `ehr_write_uncertain`, `merge_not_confirmed`, `merge_failed_in_ehr` or `merged_elsewhere`; null otherwise. errorMessage: type: string nullable: true requiresReconciliation: type: boolean description: >- True while the outcome is unknown: check the EHR before merging again. requestedAt: type: string completedAt: type: string nullable: true updatedAt: type: string required: - id - status - patientId - intoPatientId - errorCode - errorMessage - requiresReconciliation - requestedAt - completedAt - updatedAt 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.