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:
Permission Lets 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.
sourcenames your system: lower-case letters, digits and dashes, for exampleopenemr. Pick one and keep it.sourceIdis 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:
outcome | Meaning |
|---|---|
Created | A new patient. |
Updated | The patient this (source, sourceId) already pointed at. |
AutoLinked | The practice turned auto-link on, and one existing patient matched exactly: your id now points at it. |
CreatedPossibleDuplicate | A 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:
pageIndexis 0-based (the first page is0);pageSizeis 1 to 200 and defaults to 25. A search sends them in its body; aGETlist takes them as query parameters. - Response:
{ "results": [ ... ], "totalRecords": 123 }.totalRecordscounts every match across all pages. - An out-of-range value is a
400namingpageIndexorpageSize. 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
| Status | Meaning | Body |
|---|---|---|
400 | Some 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. |
403 | Your application has no account, or lacks the permission. | A problem with the reason. |
404 | No such record on this account. | A problem with the reason. |
409 | A 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.
| State | What it means | What you can do |
|---|---|---|
Draft | Saved without being checked. | Edit it, or check it (POST /claims/{claimId}/check). |
NeedsAttention | The 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. |
Ready | The check passed. | Send it (POST /claims/submit, with claimIds or allReady). |
Submitted | Sent to the clearinghouse in an 837P file. | Wait for the clearinghouse. |
ClearinghouseAccepted / ClearinghouseRejected | The clearinghouse's answer. | A rejected claim is corrected and resubmitted. |
PayerAccepted / PayerRejected | The payer's acknowledgement, before adjudication. | A rejected claim is corrected and resubmitted. |
Paid, PartiallyPaid, PatientResponsibility, Denied | The payer's decision, from the ERA. | Replace or void it if it needs correcting. |
Closed | Nothing 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:
- Upsert the patient (
PUT /external-links/patients). - Upsert the visit (
PUT /encounters/external). - Build the claim (
POST /encounters/{encounterId}/claim). It comes backReadyorNeedsAttention. - Send the Ready claims (
POST /claims/submit). - Follow each claim's
status, or itstimeline, 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.