Requests for Authorization

Enable treatment access and resolve saved records

Requests for Authorization (RFAs) are separate from bills. The organization must have treatmentBilling enabled. Server API keys use rfas:read and rfas:write; browser sessions use the narrower rfas:read, rfas:create, rfas:edit, rfas:act, and rfas:sign permissions appropriate to the user. Opening stored RFA documents also needs documents:read. Browser RFA access requires an organization-wide session and its exact allowed origin.

A draft needs a saved claim, its matching patient, and a rendering provider in the same organization. The dashboard loads authorized saved records and lets the user choose them by name. To let authorized users add a patient and injury from the RFA picker, enable canCreateClaim with the required server access. Existing patient claims can also come from bills. Manage rendering providers in billing settings. A display name, external case ID, or NPI is not a substitute for a saved MindBill ID in a custom API integration. Bill-scoped sessions cannot access RFAs.

Mount the prebuilt dashboard

React 0.73.0's RfaDashboard handles filters, status totals, request details, draft creation and editing, clinical PDF upload, signing preview and authorized signature, packet and cover-sheet review, claims administrator destinations, explicit fax sending, and delivery evidence. It also records receipt evidence, information requests and responses, item decisions, and a task board with incoming response review. Supply a separate host session endpoint for the authorized RFA permissions.

"use client";
import { RfaDashboard } from "@mindbill/react";

export function Authorizations() {
  return <RfaDashboard
    sessionEndpoint="/api/mindbill/rfa-session"
    permissions={["create"]}
    environment="sandbox" />;
}
// Your backend authenticates the user and issues an organization-wide session
// with rfas:read and rfas:create, restricted to your exact application origin.
// Show create only to authorized users; permissions defaults to [] (read-only).
// No initialDraft or custom save handler is required.

With create permission, “New authorization request” opens a searchable patient claim and rendering physician picker. Search claims by patient name or claim number, and physicians by name or NPI. Confirm the saved records, continue to the treatment editor, and save an unsigned draft. “Back to patient and physician” preserves treatment edits while you review the selection. No initialDraft or custom save handler is required. You can still supply an authorized initialDraft to start directly in the treatment editor, or use claimId and renderingProviderId to constrain the saved-record choices.

The dashboard works without a custom continuation page. Its optional onContinue adds an “Open in your application” action. All changes require an explicit user action; rendering the dashboard never signs or sends. The default environment is sandbox, where fax delivery stays disabled. For a custom interface, browser 0.47.0 exports createRfaClient with getCreationContext, list, get, createDraft, updateDraft, getDocument, uploadDocument, prepareSigning, sign, previewPacket, sendFax, and refreshFaxes.

For custom saved-record pickers, getCreationContext calls GET /partner/v2/browser/rfas/creation-context. This lookup is a browser-session-only exception to the shared business routes and requires rfas:create, an organization-wide session, and treatment access. Use search and cursor for claims, providerSearch and providerCursor for physicians, and limit (default 50, maximum 100). Optional claimId and renderingProviderId constrain the choices. Raw JSON returns data.claims, data.renderingProviders, data.nextCursor, and data.renderingProvidersNextCursor; the SDK unwraps data. Reset the corresponding cursor when changing a search or filter.

Grant rfas:read for the list, detail, and packet; documents:read for document/signing previews; and payers:read for the destination directory. Match the component's permissions controls to server scopes: create → rfas:create, edit → rfas:edit, sign → rfas:sign, send → rfas:act, and act → rfas:act. The act control enables recording review evidence and updating follow-up tasks; send controls fax delivery separately. The server enforces access independently of these UI props. Before signing, save the physician's signature once in MindBill → Settings → Rendering providers. The public BillingSettings profile does not accept signature fields. Provide actorReference as the stable authenticated human ID when enabling signing; never use an API key as the signer identity. An authorized human must review the exact preview and confirm physician authorization.

Create the draft and review the signed form

Capture the treatment items and diagnoses, requesting provider, claims administrator, rationale, request/review type, and any expedited-review information. React's RfaDraftForm provides a structured editor; the treatment quickstart shows its draft input. The dashboard includes “Edit request draft” for unsent, unreceived requests in draft or ready status. Edit service rows, diagnoses, rationale, and review details while retaining the saved claim and provider relationship.

Add supporting clinical PDFs in the same creation form before saving the draft. The dashboard saves the request and attaches the selected files. If an upload fails, the saved draft remains available and the dashboard reports how many files attached so the user can add the remainder before signing. If your application owns the form instead, use the server API example below with saved, authorized records.

// Server-side example. Resolve these saved IDs within the authorized organization.
const response = await fetch("https://app.mindbill.org/partner/v2/rfas", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.MINDBILL_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "rfa-example-plan-1",
  },
  body: JSON.stringify({
    claimId: savedClaim.id,
    patientId: savedClaim.patientId,
    renderingProviderId: savedProvider.id,
    employeeName: reviewedEmployeeName,
    providerName: reviewedProviderName,
    items: [{ diagnosisCode: "M54.50", serviceDescription: "Reviewed treatment plan" }],
  }),
});
if (!response.ok) throw new Error("Unable to save authorization request");
const { data: rfa } = await response.json();
// Persist rfa.id with your treatment plan. This saves an unsigned draft; it sends no fax.

Generate the form with POST /rfas/{rfaId}/form. Generation alone does not sign the request or make it ready to send. Upload a reviewed, signed form as an rfa_form document with its actual signing date, or use the signing-preview and sign endpoints with an authorized signer. Keep the signed form and relevant clinical support in the RFA's document list.

For a custom editor, call createRfaClient().updateDraft(rfa.id, replacement, idempotencyKey). Send the current contentRevision as expectedRevision and the complete replacement draft, including every retained item. Retain existing item IDs, omit IDs for new items, and omit rows you intend to remove. Claim, patient, and rendering provider relationships are immutable. Reuse the same idempotency key only for retries of the same edit.

Review the authorization destination and exact packet

Use the claims administrator's authorization contact or utilization review destination. It can differ from the destination used to send bills. RfaAuthorizationDestination provides the React destination control. Confirm the intended recipient and fax number before sending; a directory match still needs user review.

Preview the packet assembled from the exact stored signed rfa_form and clinical supporting PDFs. The server verifies stored hashes and PDF content. Packet assembly does not transmit anything. When no stored fax cover is selected, packet assembly generates a cover sheet. Review the complete packet and cover details before authorizing the send.

Live signing and sending use the configured MindBill-managed return fax number automatically; users do not choose a personal return number. A dedicated managed number must be configured for the organization before live use. Number provisioning is currently a setup operation arranged with MindBill, not a self-service React control or partner API. Incoming responses are scoped to the receiving organization and developer environment; ambiguous attribution is not a basis for cross-organization matching. Use sandbox to test drafts and review states without contacting a real claims administrator. Keep RFA packets separate from ordinary bill attachments and routing.

Track the request and each treatment item

List RFAs with filters for claim, rendering provider, status, and inclusive UTC creation dates. The list's summary covers the complete filtered result, while nextCursor pages through records. A dashboard should show draft/ready requests, submission and receipt evidence, requests for information, deferred review, item decisions, and follow-up work.

Read transmissions and events for the history. With act permission, the dashboard records receipt with a proof document or provider reference, information requests, responses that have already been delivered, and approval, modification, or denial for pending treatment items. Recording an information response does not send its documents. Upload actual utilization review evidence as ur_response; modified or denied decisions also need an imr_form. Mixed decisions remain visible per item. Review the server-calculated clock after each change.

Follow-up tasks and calculated deadlines help staff prioritize work; they do not establish authorization. Track scheduling for approved treatment separately from the authorization decision. Copy a prior RFA or use a template to start another request without changing the prior signed record.

For a custom interface, createRfaLifecycleClient exports recordReceipt, recordInformationRequest, recordInformationResponse, recordDecisions, listFollowUps, and updateFollowUp. Mutations require an idempotency key. RfaLifecycleControls provides these controls separately from the full dashboard. It updates backend-derived follow-up tasks, including assignment, snoozing, outcome, notes, and evidence-review disposition. These controls do not send notifications.

Work the task board and incoming responses

Open “Tasks and response inbox” in RfaDashboard. The board groups work into Due, Scheduled, and Completed: an open task is scheduled while its next follow-up time (or due time when unsnoozed) is in the future, and completed only when the backend resolves its underlying work. Task types cover missing supporting documents, sending, failed or unconfirmed delivery, no response, information requests, deadline review, Post UR, and treatment scheduling.

No response: review unanswered treatment items and the server-calculated response deadline. Log the contact outcome and note, then choose the next follow-up time. Rescheduling a task does not change the utilization review deadline or establish approval. A partial decision leaves unaddressed treatments pending and their follow-up work open.

Match UR: review the incoming fax PDF, find its patient, claim, and RFA, and explicitly confirm the match. The paginated inbox offers scoped suggestions; OCR is not a clinical decision. Matching attaches the actual response as a ur_response document and opens Post UR. It does not invent a receipt timestamp or mark treatment approved.

Post UR: open the attached response and record decisions only for the treatments addressed by that evidence. If the request still needs confirmed receipt, record the verified receipt first. Save the decisions with their response document, then explicitly complete the document review with a note and confirmation that all decisions in that response were recorded. Correspondence containing no new decision has a separate review disposition. Neither opening the PDF nor matching it completes this work.

For a separate work queue, mount RfaTaskBoard with the same session options, optional patientId, claimId, and renderingProviderId filters, and an onSelect(rfaId, responseDocumentId?) handler that opens the request and response. Enable permissions={["act"]} only for authorized staff with rfas:act. Scoped boards show matching follow-up tasks; the unmatched fax inbox appears only in the organization-wide board.

Custom interfaces use createRfaLifecycleClient: listFollowUps and updateFollowUp for tasks; listInboundFaxes, getInboundFaxContent, and matchInboundFax for incoming responses. Use returned cursors to page through either list. Inbox access requires an organization-wide session; patient or bill customer scopes cannot access it. Match mutations require an idempotency key.

Corrections, receipt review, and scheduling

The dashboard provides per-treatment decision corrections and appointment controls. Requested-information receipt review is available through the API. For custom interfaces, fetch the current record immediately before changing it and keep the server's version and evidence guards.

• Correct a decision: post to /rfas/{rfaId}/decision-corrections with the item's current expectedDecisionEventId, a reason, and the complete replacement decision with its response evidence. Corrections preserve the previous event in the audit history. A stale decision, linked bill, or scheduled treatment can prevent correction.
• Review requested-information receipt: post to /rfas/{rfaId}/information-receipt-review with the current expectedExceptionEventId, all affected information request IDs, the exact stored complete-request receipt time, reviewer receipt time, and evidence document IDs. The required confirmations attest that only missing information was requested, all requested information was received, and standard review applies. The server rejects stale or unsupported histories and preserves the original receipt baseline.
• Track scheduling: first read /rfas/{rfaId}/scheduling. Update an item using its fresh expectedVersion and authorizationToken. A scheduled disposition includes the appointment time with timezone, provider name, and location; no-appointment and canceled dispositions include a reason.

Link authorization to the treatment bill

After the service occurs, create a professional bill with reviewed dates, procedure codes, charges, and line-level diagnosis pointers. Set serviceLines[].rfaItemId when a line relates to a saved RFA item. The server validates the relationship and authorization constraints; the presence of the ID alone is not evidence of approval.

Attach relevant authorization or Medical Provider Network (MPN) records as optional other bill documents when needed. See authorization and network documents. The full RFA packet stays in its separate authorization workflow.

Canonical API map

Short suffixes in each row continue after /rfas/{rfaId}; top-level paths start with /rfa. All routes below are relative to https://app.mindbill.org/partner/v2. Read the OpenAPI contract for request fields, permissions, response envelopes, and idempotency requirements. Browser and server clients use the same business routes with their respective credentials.