> ## 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. # Add a directory payer to the practice > Adds a payer from `GET /payers/directory` to the practice's payer list as NON-contracted, with the defaults a biller gets saving it unedited (medical, accepts assignment, electronic 5010 claims when the payer takes them, no fee schedules). The returned `payerId` works with `POST /patients/{id}/insurance:exact` immediately. 201 when this request added the payer; 200 with the existing payer when the practice already has it — never a duplicate. 422 `directory_payer_not_found` when the directory has no payer with that `directoryPayerId` and `name`; 422 `payer_inactive_in_ehr` when the practice has it but deactivated it (a biller must reactivate it). 400 `capability_unsupported` on EHRs that cannot add payers (see `GET /payers/capabilities`). 409 `ehr_write_uncertain` means the add may have reached the EHR. That key then keeps answering 409 for 24 hours, so retry with a NEW key: the payer list is checked before any add, so the retry returns the payer if the first request added it. Requires write:payers. ## OpenAPI ````yaml /openapi-v2.json post /payers openapi: 3.0.0 info: title: Max AI Public API description: API for third-party marketplace apps version: '2.0' contact: {} servers: - url: https://api.maxcare.ai/v2 security: [] tags: [] paths: /payers: post: tags: - Payers summary: Add a directory payer to the practice description: >- Adds a payer from `GET /payers/directory` to the practice's payer list as NON-contracted, with the defaults a biller gets saving it unedited (medical, accepts assignment, electronic 5010 claims when the payer takes them, no fee schedules). The returned `payerId` works with `POST /patients/{id}/insurance:exact` immediately. 201 when this request added the payer; 200 with the existing payer when the practice already has it — never a duplicate. 422 `directory_payer_not_found` when the directory has no payer with that `directoryPayerId` and `name`; 422 `payer_inactive_in_ehr` when the practice has it but deactivated it (a biller must reactivate it). 400 `capability_unsupported` on EHRs that cannot add payers (see `GET /payers/capabilities`). 409 `ehr_write_uncertain` means the add may have reached the EHR. That key then keeps answering 409 for 24 hours, so retry with a NEW key: the payer list is checked before any add, so the retry returns the payer if the first request added it. Requires write:payers. operationId: PayersPublicController_createPayer parameters: - 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/CreatePayerBody' responses: '200': description: Success '201': description: Created content: application/json: schema: $ref: '#/components/schemas/CreatePayerSuccessResponse' '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' '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: CreatePayerBody: type: object properties: directoryPayerId: type: string description: '`directoryPayerId` from `GET /payers/directory`' maxLength: 50 name: type: string description: >- The directory entry's `name`, exactly as returned — the EHR keys payers on national id AND name maxLength: 255 instanceId: type: string description: >- EHR instance to add the payer to; same default as `GET /payers/directory` required: - directoryPayerId - name CreatePayerSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/CreatedPayerData' 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 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 CreatedPayerData: type: object properties: payerId: type: string description: >- Max AI payer id, usable with `POST /patients/{id}/insurance:exact` immediately name: type: string directoryPayerId: type: string contracted: type: boolean description: >- False for a payer this request added; an existing payer reports its own state created: type: boolean description: >- True when this request added the payer (201); false when the practice already had it (200) required: - payerId - name - directoryPayerId - contracted - created 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.