Skip to main content

Getting Started with SharpRevCycle

SharpRevCycle is ClaimRev's billing module: patients and their coverage, visits (encounters), claims built from them, and the claims' journey through the clearinghouse and the payer. The API under /api/SharpRevCycle/v1 is the same one the ClaimRev portal uses, so anything you send shows up on the practice's screens straight away.

This page covers what every SharpRevCycle call has in common. The endpoints themselves are in the SharpRevCycle section of the sidebar, grouped as a practice meets them: setup first, then patients, encounters and claims.

Before you start​

  • The practice bills in SharpRevCycle. ClaimRev switches an account's billing to SharpRevCycle; ask your ClaimRev contact before you start.

  • Your client application needs the SharpRevCycle permissions. Ask your ClaimRev contact to link them to its role:

    PermissionLets your application
    sharprevcycle:readRead and search setup, patients, encounters, claims and their history.
    sharprevcycle:writeCreate and update payers, providers, facilities, patients, coverage, encounters and claims.
    sharprevcycle:submitSend Ready claims to the clearinghouse, and resubmit, replace or void them.

    Running a real-time eligibility check also needs sharprevenue:realtime.

  • Setup that is done in the portal (practice settings, fee schedules, contracts, encounter types and their rules, telehealth rules) can be read through the API, so your system can show it, but is changed by the practice in the portal.

Authentication​

SharpRevCycle uses the same bearer token as the rest of the ClaimRev API. Follow Authentication to get one, then send it on every request:

GET /api/SharpRevCycle/v1/payers HTTP/1.1
Host: testapi.claimrev.com
Authorization: Bearer <access token>

Use the test environment (https://testapi.claimrev.com) while you build. Test and production never share data or credentials.

The account comes from your token​

No SharpRevCycle request carries an account number. Every call works on the default account of the signed-in application, taken from the token, and you cannot name another one.

  • An id that belongs to another account behaves exactly like an id that does not exist: 404.
  • If you serve several practices, use one client application per practice (see Client Applications). Each application's token reaches that practice only.

Your ids: upserts keyed by (source, sourceId)​

Your system already has its own ids for patients and visits. SharpRevCycle remembers them for you as external links, so you never have to store ours.

  • source names your system: lower-case letters, digits and dashes, for example openemr. Pick one and keep it.
  • sourceId is your system's id for the record, exactly as you hold it (case matters), up to 100 characters.

The same (source, sourceId) always lands on the same record. The first send creates it; every later send updates it. Send it again after a change in your system and the record follows, with no duplicate.

Patients​

PUT /api/SharpRevCycle/v1/external-links/patients
{
"source": "openemr",
"sourceId": "PT-10042",
"patient": {
"firstName": "Bugs",
"lastName": "Bunny",
"dateOfBirth": "1940-07-27",
"gender": "M",
"addressLine1": "2 Rabbit Hole",
"city": "Albuquerque",
"state": "NM",
"zipCode": "871010002"
},
"coverages": [
{ "payerId": "<a payer id from GET /payers>", "memberId": "TOON00001", "groupNumber": "TOONGRP01", "relationshipCode": "18" }
]
}

The response says what happened (outcome) and gives the SharpRevCycle patientId:

outcomeMeaning
CreatedA new patient.
UpdatedThe patient this (source, sourceId) already pointed at.
AutoLinkedThe practice turned auto-link on, and one existing patient matched exactly: your id now points at it.
CreatedPossibleDuplicateA new patient that looks like an existing one. The pair waits in the practice's possible-duplicates queue (GET /duplicates).

On an update, a field you leave blank keeps the stored value. Coverage is matched on payer and member id; coverage you do not list is left alone, so sending one coverage never removes the others.

To find what one of your ids points at, POST /external-links/lookup with source and sourceId (a POST, so the id never appears in a URL). DELETE /external-links/{externalLinkId} removes the link; the patient stays.

Encounters​

PUT /api/SharpRevCycle/v1/encounters/external
{
"source": "openemr",
"sourceId": "VISIT-20240110-01",
"patientSourceId": "PT-10042",
"encounter": {
"encounterDate": "2024-01-10",
"placeOfServiceCode": "11",
"diagnosisCodes": ["F41.1"],
"procedures": [ { "procedureCode": "90837", "diagnosisPointers": [1] } ]
}
}

Name the patient either by encounter.patientId or, as here, by patientSourceId: the patient's id in the same source. Once a claim has been built from an encounter, its codes no longer change.

Paging​

Every SharpRevCycle search and queue pages the same way.

  • Request: pageIndex is 0-based (the first page is 0); pageSize is 1 to 200 and defaults to 25. A search sends them in its body; a GET list takes them as query parameters.
  • Response: { "results": [ ... ], "totalRecords": 123 }. totalRecords counts every match across all pages.
  • An out-of-range value is a 400 naming pageIndex or pageSize. It is never quietly clamped.

Versions and conflicts​

Records you can edit carry a version. Send back the version you read when you update. If someone changed the record in between, the update is refused with 409 and "This record was changed by someone else after you opened it." Read it again and reapply your change.

Errors​

StatusMeaningBody
400Some of the details need correcting.A validation problem: errors names each field, and code is set for refusals your code may want to tell apart.
403Your application has no account, or lacks the permission.A problem with the reason.
404No such record on this account.A problem with the reason.
409A stale version, a duplicate, or an action the record's state does not allow.A problem; some carry a code so your code can tell them from a stale version.

The detail of a problem is written to be shown to a person. It never contains patient data.

The claim lifecycle​

A claim moves through these states. The status field always says where it is, and GET /claims/{claimId}/timeline shows every step with the clearinghouse and payer responses.

StateWhat it meansWhat you can do
DraftSaved without being checked.Edit it, or check it (POST /claims/{claimId}/check).
NeedsAttentionThe claim check found something to fix. issues lists each one.Fix it and save; it is checked again. The account's queue is GET /claims/needs-attention.
ReadyThe check passed.Send it (POST /claims/submit, with claimIds or allReady).
SubmittedSent to the clearinghouse in an 837P file.Wait for the clearinghouse.
ClearinghouseAccepted / ClearinghouseRejectedThe clearinghouse's answer.A rejected claim is corrected and resubmitted.
PayerAccepted / PayerRejectedThe payer's acknowledgement, before adjudication.A rejected claim is corrected and resubmitted.
Paid, PartiallyPaid, PatientResponsibility, DeniedThe payer's decision, from the ERA.Replace or void it if it needs correcting.
ClosedNothing more to do.

Draft, NeedsAttention and Ready are the only states you can edit. From Submitted on, a claim is corrected through POST /claims/{claimId}/resubmit (ClaimRev chooses a corrected original or a replacement), POST /claims/{claimId}/void, and POST /claims/{claimId}/cancel-void. Each claim's allowedActions tells you which of these it allows right now and, when it allows none, why. The Rejected and denied queue is POST /claims/rejections.

A typical flow from an EMR:

  1. Upsert the patient (PUT /external-links/patients).
  2. Upsert the visit (PUT /encounters/external).
  3. Build the claim (POST /encounters/{encounterId}/claim). It comes back Ready or NeedsAttention.
  4. Send the Ready claims (POST /claims/submit).
  5. Follow each claim's status, or its timeline, as the clearinghouse and payer answer.

Healthie is a portal feature, not an API​

Practices that chart in Healthie can connect it to SharpRevCycle in the portal (Setup, Healthie). ClaimRev then imports their claims from Healthie, sends them, and writes each claim's status, and the ERA payments the practice posts, back to Healthie, all from the portal. None of that is part of this API, and the Healthie screens' endpoints are not published here.

If your system is not Healthie, use the upserts above.