Building a Claim Search Screen

A claim-search screen is usually the heart of an integrator's UI: a filterable, paged grid of claims with row-level drill-downs and a few common bulk actions (reprocess, mark worked, void, replace). This guide maps that workflow onto ClaimRev's public API so you can build a screen that feels native — without reinventing logic that ClaimRev already exposes.

The recipe below mirrors what the ClaimRev portal does at /claims/search, restricted to public endpoints external integrators can call.

Mental model

A typical claim-search workflow has six layers:

1. Page load — fetch lookups your filters need (e.g., the claim status list)
2. Build a filter model — the user picks date range, payer, patient, status, etc.
3. Run the search — paged, sorted, returning a result set + total count
4. Drill in — when the user expands a row, fetch errors, notes, related claims, attachments
5. Act on a claim — reprocess, mark worked, mark void, add/remove an error, create a replacement
6. Export — CSV download for the current filter set

Each layer maps to a small number of endpoints. The single primary call is POST /api/ClaimView/v1/SearchClaimsPaged; everything else is supporting.

Step 1: Authenticate

Get a bearer token before doing anything else. See Authentication. The rest of this guide assumes every request includes:

Authorization: Bearer <token>

Step 2: Load lookups on page mount

The only API-backed lookup you need for a basic claim search is the claim status list — the values shown in the status filter dropdown.

GET /api/ClaimView/v1/GetClaimStatuses

Response: an array of { id, name, description }-shaped status objects. Keep them in memory; the list is small and effectively static across a session.

The other common dropdown values (claim types — Professional / Institutional / Dental — and the file-acceptance / payer-acceptance status enums) are stable enough that you can hardcode them in your client. The ClaimRev portal hardcodes them too.

Step 3: Build the search model

SearchClaimsPaged accepts a ClaimSearchModel with paging info. Most integrators use a small fraction of the available fields.

The fields most commonly bound to UI controls:

Filter UI	ClaimSearchModel field
Account scoping (if the user has access to multiple)	accountNumber or accountNumbers
Date received (start / end)	receivedDateStart, receivedDateEnd
Service date (start / end)	serviceDateStart, serviceDateEnd
Status (multi-select)	statusIds, excludeStatusIds
Status group (Accepted / Rejected / Processing)	claimStatusGroup
Claim type (P / I / D)	claimTypeIds
Payer (id or name)	payerNumber, payerName
Patient (first / last / DOB / gender)	patientFirstName, patientLastName, patientBirthDate, patientGender
Trace number (ISA13)	traceNumber or traceNumbers
Patient control number (CLM01)	patientControlNumber or patientControlNumbers
Payer control number	payerControlNumber or payerControlNumbers
Source input file	inputFileObjectId (use the id from GetFileList)
Free-text error message	errorMessage

And the paging block (required — this is the whole point of using the Paged variant):

{
  "pagingSearch": {
    "pageIndex": 0,
    "pageSize": 25,
    "sortField": "receivedDate",
    "sortDirection": "desc"
  }
}

A reasonable starting model for "show me everything received in the last 7 days":

{
  "receivedDateStart": "2026-04-20T00:00:00Z",
  "receivedDateEnd": "2026-04-27T23:59:59Z",
  "pagingSearch": {
    "pageIndex": 0,
    "pageSize": 25,
    "sortField": "receivedDate",
    "sortDirection": "desc"
  }
}

The full schema is in the API Reference — many additional fields exist for niche filters (claim age buckets, payment-advice status arrays, etc.).

Step 4: Run the search

POST /api/ClaimView/v1/SearchClaimsPaged
Content-Type: application/json
Authorization: Bearer <token>

Body: the ClaimSearchModel you built in Step 3.

The response is a paged result containing your claims plus a total count for paging UI:

• An array of claim view models (one per match) — each carrying everything the screen needs to render a row: identifying info, status, dates, payer info, dollar totals, acceptance status, error counts
• The total record count — drive your "showing N of M" UI from this

The full claim shape is in the API Reference; treat any field you don't recognize as opaque rather than dropping it.

Step 5: Pagination

When the user changes pages, repeat Step 4 with an updated pagingSearch.pageIndex. Don't change other filter values mid-paging — if the user adjusts a filter, reset pageIndex to 0 and re-run.

A minimal client state machine looks like:

filtersChanged() → searchModel.pagingSearch.pageIndex = 0 → runSearch()
pageChanged(n)   → searchModel.pagingSearch.pageIndex = n → runSearch()
sortChanged(...) → update sortField/sortDirection, reset pageIndex to 0 → runSearch()

Step 6: Drill into a row

When the user expands or selects a claim row, you'll typically want to show errors, notes, related claims, and any attachment requests. Each is a separate endpoint, and most are GETs by claim id — easy to fan out in parallel.

What you want	Endpoint
Validation errors and payer rejections	GET /api/ClaimView/v1/GetClaimErrors?claimId={id}
User-authored notes on the claim	GET /api/ClaimView/v1/GetClaimNotes?claimId={id}
Replacement / void / siblings of this claim	GET /api/ClaimView/v1/GetRelatedClaims?claimId={id}
Pending attachment / 275 requests on this claim	GET /api/ClaimView/v1/GetClaimAttachmentRequests?claimId={id}

Fetching all four in parallel on row expand is fine — they're cheap, and the responses are small.

Step 7: Acting on a claim

The portal's bulk actions break into a handful of public endpoints. Each accepts a single claim or, where bulk semantics are supported, an array.

Action	Endpoint	Notes
Mark a claim as worked	POST /api/ClaimManager/v1/MarkClaimAsWorked	Sets the "is worked" flag — useful for queue/workflow UIs
Mark a claim as void	POST /api/ClaimManager/v1/MarkClaimAsVoid	Voids without sending a payer-side void; for cleanup of internal state
Reprocess (re-run validation/routing)	POST /api/ClaimManager/v1/ReprocessClaims	Pass an array of claim ids; flips status to Reprocess so the engine picks them up again
Add an arbitrary error/note	POST /api/ClaimManager/v1/AddErrorToClaim	Surfaces in GetClaimErrors; useful for tagging things the user noticed
Remove an error	POST /api/ClaimManager/v1/RemoveClaimError	Inverse of the above

Each request takes a small JSON body containing the claim id(s) and any action-specific fields. See the API Reference for the exact shapes — they're small.

Replacement and void claims

If the user needs to issue a replacement (XX7) or void (XX8) for a previously submitted claim, ClaimRev exposes that as a single call:

POST /api/ClaimEditor/v1/CreateReplacementVoidClaim
Authorization: Bearer <token>
Content-Type: application/json

The body identifies the source claim and the desired type (replacement vs void). ClaimRev builds the new 837 with the correct claim frequency code and original-reference linkage.

After this call, the new claim flows through the normal submission lifecycle — batched send, 999, 277CA, eventual ERA. You don't need to manage that yourself.

Step 8: Export the current search

CSV export uses the same ClaimSearchModel you built in Step 3 — minus the paging, since the export is the full result set.

POST /api/ClaimView/v1/SearchClaimsCsv
Content-Type: application/json
Authorization: Bearer <token>

The response includes a fileText string (the CSV) and a fileName. Wire it up to a browser download trigger or write it to a file in a server-side integration.

Putting it together

A simplified happy path through the workflow:

1. User opens the screen
   → GET /api/ClaimView/v1/GetClaimStatuses
2. User adjusts filters and clicks Search
   → POST /api/ClaimView/v1/SearchClaimsPaged    (with pagingSearch)
3. Render rows; user clicks page 2
   → POST /api/ClaimView/v1/SearchClaimsPaged    (pageIndex: 1)
4. User expands a row
   → GET  /api/ClaimView/v1/GetClaimErrors        \
   → GET  /api/ClaimView/v1/GetClaimNotes          | in parallel
   → GET  /api/ClaimView/v1/GetRelatedClaims       |
   → GET  /api/ClaimView/v1/GetClaimAttachmentRequests /
5. User selects 5 claims and clicks Reprocess
   → POST /api/ClaimManager/v1/ReprocessClaims    (with the 5 ids)
6. User exports the search
   → POST /api/ClaimView/v1/SearchClaimsCsv

That's the full screen — six endpoints for the core experience, plus a few more if you support row-level actions like marking worked, voiding, adding/removing errors, or creating a replacement.

What this guide deliberately does not cover

The portal's /claims/search page does several things that aren't part of the public API surface and shouldn't be modeled in a third-party integration:

• Workflow assignment, queues, tags, "next status" — these are portal-internal organizational tools managed by ClaimRev users. They use admin-scoped endpoints (/api/Workflow/*, /api/ClaimManagement/AssignWorkflow, etc.) that aren't in the public doc group.
• Saved searches and user preferences — convenience features for the portal user; the public API doesn't expose them. If your screen needs saved filters, persist them in your own data store.
• The Reconciliation and Provider Summary tabs on the portal page — these are aggregations over the same claim data, but the endpoints (/api/RealTimeReports/*) are portal-internal. Build equivalent aggregations from SearchClaimsPaged results yourself if you need them.
• Real-time claim status request from the row menu — that uses SharpRevenue/RunClaimStatusRequest which is a separate workflow documented elsewhere.
• Status-only shortcut endpoints like ChangeClaimStatusOnly — these are portal optimizations. The public path is ReprocessClaims (or, for narrower changes, AddErrorToClaim / RemoveClaimError).

If your integration wants any of those features, contact ClaimRev support — some can be enabled case-by-case; others are roadmap.

Endpoint cheat sheet

Page load:
  GET  /api/ClaimView/v1/GetClaimStatuses

Search:
  POST /api/ClaimView/v1/SearchClaimsPaged
  POST /api/ClaimView/v1/SearchClaimsCsv

Row drill-down (parallel):
  GET  /api/ClaimView/v1/GetClaimErrors?claimId={id}
  GET  /api/ClaimView/v1/GetClaimNotes?claimId={id}
  GET  /api/ClaimView/v1/GetRelatedClaims?claimId={id}
  GET  /api/ClaimView/v1/GetClaimAttachmentRequests?claimId={id}

Row / bulk actions:
  POST /api/ClaimManager/v1/MarkClaimAsWorked
  POST /api/ClaimManager/v1/MarkClaimAsVoid
  POST /api/ClaimManager/v1/ReprocessClaims
  POST /api/ClaimManager/v1/AddErrorToClaim
  POST /api/ClaimManager/v1/RemoveClaimError

Replacement / void claim:
  POST /api/ClaimEditor/v1/CreateReplacementVoidClaim