> ## 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. # Create a prior authorization on a policy > Writes one authorization to the EHR, live; nothing is de-duplicated here, so read `GET …/prior-authorizations` first. Send exactly one of `numVisits` or `unlimited: true`. `documentRef` (a document `ref` from `POST /v4/patients/{id}/documents` or `GET /v4/ehr/patients/{id}/documents`) is linked to the new authorization on ModMed; `documentLinked: false` means the authorization exists but the link did not land. On ModMed, `note` is Additional Notes, `assignedProviderRef` is a provider `id` from the reads, and `referringProvider` is matched by individual NPI to the practice's active referral contacts (a group NPI is not matched). `ignoredFields` lists sent fields that were not written: on ModMed only `referringProvider` when it could not be matched to a referral contact (none has that NPI, or the lookup failed); on EZDerm `authType`, `active`, `note`, `appointmentTypeIds`, `assignedProviderRef`, `referringProvider` and `documentRef` (EZDerm stores `description` as its note). Send an `Idempotency-Key`: a replay returns the first result for 24 hours. 409 `ehr_write_uncertain` when the EHR's answer is unknown: re-read the list before sending again. 422 `prior_auth_refused` when the EHR refused it (nothing written). 404 for an unknown patient, policy or `documentRef`. Requires write:prior_authorizations. ## OpenAPI ````yaml /openapi-v4.json post /ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations 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}/insurances/{policyRef}/prior-authorizations: post: tags: - EHR live reads summary: Create a prior authorization on a policy description: >- Writes one authorization to the EHR, live; nothing is de-duplicated here, so read `GET …/prior-authorizations` first. Send exactly one of `numVisits` or `unlimited: true`. `documentRef` (a document `ref` from `POST /v4/patients/{id}/documents` or `GET /v4/ehr/patients/{id}/documents`) is linked to the new authorization on ModMed; `documentLinked: false` means the authorization exists but the link did not land. On ModMed, `note` is Additional Notes, `assignedProviderRef` is a provider `id` from the reads, and `referringProvider` is matched by individual NPI to the practice's active referral contacts (a group NPI is not matched). `ignoredFields` lists sent fields that were not written: on ModMed only `referringProvider` when it could not be matched to a referral contact (none has that NPI, or the lookup failed); on EZDerm `authType`, `active`, `note`, `appointmentTypeIds`, `assignedProviderRef`, `referringProvider` and `documentRef` (EZDerm stores `description` as its note). Send an `Idempotency-Key`: a replay returns the first result for 24 hours. 409 `ehr_write_uncertain` when the EHR's answer is unknown: re-read the list before sending again. 422 `prior_auth_refused` when the EHR refused it (nothing written). 404 for an unknown patient, policy or `documentRef`. Requires write:prior_authorizations. operationId: EhrPublicController_createPriorAuthorization parameters: - name: x-session-token in: header description: >- App Bridge session token. The user's own EHR login reads when they have one (`actingAs: user`). required: false schema: type: string - name: patientId required: true in: path schema: type: string - name: policyRef required: true in: path description: The policy's `ref` or `pol_` id schema: type: string - name: x-session-token required: true in: header 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/CreateEhrPriorAuthorizationBody' responses: '201': description: Created content: application/json: schema: $ref: >- #/components/schemas/CreateEhrPriorAuthorizationSuccessResponse '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' '503': description: EHR integration unavailable content: application/json: schema: $ref: '#/components/schemas/PublicApiServiceUnavailableResponse' security: - api-key: [] components: schemas: CreateEhrPriorAuthorizationBody: type: object properties: authorizationNumber: type: string description: The payer's authorization number example: A12345678 authType: type: string enum: - authorization - referral default: authorization active: type: boolean default: true startDate: type: string nullable: true description: '`YYYY-MM-DD`' endDate: type: string nullable: true description: '`YYYY-MM-DD`, on or after `startDate`' numVisits: type: integer nullable: true minimum: 1 maximum: 99 description: 'Send this or `unlimited: true`, not both.' unlimited: type: boolean default: false description: No visit cap. Send this or `numVisits`, not both. description: type: string maxLength: 500 example: Mohs surgery, left cheek note: type: string nullable: true maxLength: 500 appointmentTypeIds: description: ModMed appointment type ids the auth covers. type: array items: type: string assignedProviderRef: type: string nullable: true description: >- A provider `id` (`prv_…`) as returned on appointments and encounters. referringProvider: nullable: true description: >- ModMed: matched by individual NPI (not a group NPI) to the practice's active referral contacts; `name` is not stored; a miss is reported in `ignoredFields`. allOf: - $ref: '#/components/schemas/PriorAuthReferringProvider' documentRef: type: string nullable: true description: >- A chart document to attach: the `ref` from `POST /v4/patients/{id}/documents` or `GET /v4/ehr/patients/{id}/documents`. required: - authorizationNumber - description CreateEhrPriorAuthorizationSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/CreateEhrPriorAuthorizationData' 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 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 PriorAuthReferringProvider: type: object properties: npi: type: string example: '1234567893' name: type: string example: Jane Doe MD required: - npi - name CreateEhrPriorAuthorizationData: type: object properties: ref: type: string description: >- The new authorization's `ref`, the same one `GET …/prior-authorizations` lists. ehr: type: string enum: - modmed - ezderm authorizationNumber: type: string example: A12345678 ignoredFields: description: Fields that were sent but not written. example: - referringProvider type: array items: type: string documentLinked: type: boolean nullable: true description: >- Null when no `documentRef` was written. False: the authorization exists but the document was not linked to it; link it in the EHR, do not create the authorization again. required: - ref - ehr - authorizationNumber - ignoredFields - documentLinked 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.