> ## 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. # Search the EHR's national payer directory > Every payer the EHR vendor knows, including ones this practice has not added, read LIVE from the EHR on each call — debounce a typeahead. Each entry says whether the practice already has the payer and, when the EHR ties it to a writable practice payer, gives its `practicePayerId` for `POST /patients/{id}/insurance:exact`. EHRs without a national directory answer 400 `capability_unsupported`; check `GET /payers/capabilities` first. Requires read:payers. ## OpenAPI ````yaml /openapi-v2.json get /payers/directory 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/directory: get: tags: - Payers summary: Search the EHR's national payer directory description: >- Every payer the EHR vendor knows, including ones this practice has not added, read LIVE from the EHR on each call — debounce a typeahead. Each entry says whether the practice already has the payer and, when the EHR ties it to a writable practice payer, gives its `practicePayerId` for `POST /patients/{id}/insurance:exact`. EHRs without a national directory answer 400 `capability_unsupported`; check `GET /payers/capabilities` first. Requires read:payers. operationId: PayersPublicController_searchDirectory parameters: - name: q required: true in: query description: Payer name or national payer id to search for schema: minLength: 2 maxLength: 100 type: string - name: instanceId required: false in: query description: >- EHR instance whose directory to search and whose payers to link to. Optional when the organization has one EHR instance; otherwise pass the patient's. schema: type: string - name: limit required: false in: query schema: minimum: 1 maximum: 100 default: 25 type: number - name: X-Organization-Id in: header required: true schema: type: string description: Target clinic organization ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PayerDirectorySuccessResponse' '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' '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: PayerDirectorySuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/PayerDirectoryData' 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 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 PayerDirectoryData: type: object properties: instanceId: type: string description: The EHR instance that was searched payers: type: array items: $ref: '#/components/schemas/DirectoryPayerResponse' required: - instanceId - payers DirectoryPayerResponse: type: object properties: directoryPayerId: type: string description: >- National (clearinghouse) payer id — pass it to `POST /payers` to add the payer name: type: string electronicClaimsSupported: type: boolean electronicAttachmentsSupported: type: boolean exactMatch: type: boolean description: The EHR's own exact-name match flag for `q` alreadyInPractice: type: boolean description: The practice already has this payer practicePayerId: type: string nullable: true description: >- The practice payer's Max AI id, usable with `POST /patients/{id}/insurance:exact` straight away. Matched by the EHR's own payer id, never by national id alone (different payers share one). Null when this instance has no writable practice payer for it. required: - directoryPayerId - name - electronicClaimsSupported - electronicAttachmentsSupported - exactMatch - alreadyInPractice - practicePayerId 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.