How to automate a payer portal, step by step

A billing team checks claim status in a payer portal one claim at a time and asks you to automate it. The first version works for a week. Then the login page adds a prompt, a session expires in the middle of a run, and the job writes nothing. The steps below build the automation so that it survives those events and leaves a record of what it saw.

Step 1: List the workflows

Sit with the people who use the portal and write down each task they do. For each task, record the inputs they type, the pages they visit, the output they copy and how often they do it. Most tasks fall into four groups.

Workflow	Portal output	HIPAA transaction
Eligibility and benefits	Coverage dates, copay, deductible, plan name	270/271
Claim status	Status, paid amount, check number, denial text	276/277
Prior authorization status	Approved, denied or pended, with dates	278
Remits and EOB download	Remittance PDF or data per check	835

The transaction column comes from the CMS list of adopted HIPAA standards. Mark each task with the fields the team actually uses.

Step 2: Check for an API or X12 path first

A portal is the last source to try. An API or an X12 transaction has a documented contract, and a portal page has none.

The CMS Interoperability and Prior Authorization final rule (CMS-0057-F) requires impacted payers to build new APIs. The CMS fact sheet names the impacted payers: Medicare Advantage organizations, state Medicaid and CHIP fee-for-service programs, Medicaid managed care plans, CHIP managed care entities and Qualified Health Plan issuers on the Federally Facilitated Exchanges. The API requirements generally begin January 1, 2027, and the exact date varies by payer type. Check the CMS rule page for the current dates.

Two of these APIs matter for portal work. The Prior Authorization API returns whether a request is approved, denied with a specific reason, or needs more information. The Provider Access API shares claims and encounter data with in-network providers, but the fact sheet excludes remittances and cost sharing from it. Remits still come from the 835 or from the portal.

Many payers also publish their own APIs. The UnitedHealthcare API page lists claim inquiry, pre-service eligibility, patient benefit check and document search, among others. Availity offers REST APIs for eligibility, claim status and service reviews, covered in how to integrate with Availity. Use the API or the transaction for every field it covers. Keep the portal for the fields that remain.

Step 3: Give each user their own credential

Portal accounts belong to people. UnitedHealthcare requires each user to create their own One Healthcare ID and answers "No" to the question of whether an ID can be shared. The same page says accounts are deactivated after 90 consecutive days of inactivity.

Map each automated session to one named user at the practice, with that user's written consent. Store the password and the second factor secret in a secrets manager, keyed by practice and user. Never run several practices through one account. Track the last successful login per account and alert the practice administrator before the inactivity limit.

For the second factor, an authenticator app secret enrolled with the administrator's consent lets your system generate the code. The payer portal integrations post covers which factors each portal accepts.

Step 4: Design the browser automation

Selectors

Find elements by label text, ARIA role or form field name. Generated CSS class names and positional XPath break when the payer rebuilds the page. Put every selector in a config file per portal, apart from the driver code.

page.get_by_label("Member ID").fill(member_id)
page.get_by_label("Date of Birth").fill(dob)
page.get_by_role("button", name="Submit").click()
page.wait_for_selector("text=Claim Status Results")

Session reuse

Log in once, then save the cookies and local storage for that account. Reuse the saved state for later jobs until the portal redirects to the login page. Each account gets its own browser context. Never share a context between two accounts.

Request rate

Run one worker per account and send searches in sequence. Pause between searches, and back off after an error page or a timeout. Schedule large batches outside office hours, so that the job does not compete with staff for the same session.

Screenshots as audit evidence

For each lookup, save a screenshot and the page HTML with the account, the request ID and a timestamp. These files contain PHI, so encrypt them and delete them on a fixed retention schedule.

Step 5: Parse results into structured data

Write each result into the same schema that the API or transaction path uses. Downstream code then does not care where the data came from. Keep the raw portal text next to each parsed field.

{
  "source": "portal",
  "payer_claim_id": "2026110400123",
  "status": "denied",
  "status_text_raw": "Denied - see letter",
  "billed_amount": "185.00",
  "paid_amount": "0.00",
  "check_number": null,
  "captured_at": "2026-11-11T14:02:11Z",
  "evidence_id": "ev_7f3a"
}

Store money as decimal strings and dates in ISO 8601. Map portal status words to your own fixed set, and send unknown words to a review queue. Validate every record against the schema before you store it.

Step 6: Detect change and repair

For each page type, store a fingerprint of the page structure: the tag tree with text removed. Compare each new page with the stored fingerprint and alert when it drifts, even if extraction still succeeds.

Keep saved HTML from real pages, with patient data removed, as test fixtures. Run the parsers against these fixtures on every change to the config. When a portal changes, save the new page as a fixture, update the selectors, and confirm the old and new fixtures both pass.

Put failed jobs in a queue with their inputs. After a repair, replay the queue. Lookups are reads, so a replay is safe. Any job that writes to the portal, such as an appeal upload, needs a check that it did not already go through.

Step 7: Review the terms of use

Read the portal terms of use and the provider agreement before you build. Look for rules on automated access, on shared credentials and on what data a user may export. The terms are often silent on automation. The Availity terms of use, for example, do not mention bots or automated tools. When the terms are silent, ask the payer and keep the answer on file. Record the practice's authorization for each account. If the payer offers an API for the same data, move to it. Splice Health returns portal, API and transaction results in one schema, so a move from portal to API does not change the data your product reads.