Creating a Replacement Claim

When a payer has already accepted a claim and you need to fix something on it, you do not resubmit it as a new original. A second original is either rejected as a duplicate or, worse, paid twice. Instead you send a replacement claim: a complete corrected copy that tells the payer which of its claims to replace.

What makes a claim a replacement

Two fields, both in loop 2300 of the 837:

X12	Editor field	What it carries
CLM05-3	claimEditorView.claimFreqCode	Claim frequency type code. 7 for a replacement, 8 for a void.
REF*F8	claimEditorView.refOriginalReference	The payer's own control number for the claim you are replacing.

Frequency codes:

Code	Meaning	Use when
1	Original	First submission of the claim. This is the default.
7	Replacement of prior claim	You are correcting a claim the payer has on file.
8	Void / cancel of prior claim	You are withdrawing the claim entirely.

Both fields, or neither works

Sending claimFreqCode of 7 without a REF*F8 is the single most common replacement failure. The payer has no way to tell which claim you mean, so it rejects the submission or treats it as a fresh original. Payers differ in how strictly they enforce this, so an acceptance from one payer is not proof the pattern is right for the next one.

A replacement is a whole claim, not a diff

Send every service line and every field, with your corrections applied. The payer discards the claim it has and stores what you send in its place. Omitting the lines that did not change will remove them from the claim.

Institutional claims. For 837I the frequency code is the third digit of the type of bill, so a replacement reads as type of bill 0117 and a void as 0118. It still lands in CLM05-3, and the original reference still goes in REF*F8 (FL64 on the UB-04).

Step 1: get the payer control number

The payer control number (also called the payer claim control number, ICN, or DCN) is assigned by the payer. You do not generate it, and neither does ClaimRev. It arrives on the 277CA claim acknowledgment, usually the day after submission, and ClaimRev stitches it onto the claim record automatically.

Retrieve it with a claim search:

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

{
  "pagingSearch": { "pageIndex": 0, "pageSize": 25 },
  "patientControlNumbers": ["ACCT-001"]
}

The fields you need off each result:

Field	Why you need it
payerControlNumber	Goes into REF*F8 on the replacement.
objectId	Identifies the claim if you use Path B below.
payerAcceptanceStatusId	Tells you whether the payer actually has the claim.

If payerControlNumber is empty, the payer has not acknowledged the claim yet and you are not ready to replace it. Check payerAcceptanceStatusId: 3 means rejected at the payer and 4 means accepted at the payer. Anything else means the 277CA has not landed. See Checking Claim Status.

A rejected claim usually does not need a replacement

If the payer rejected the claim at the acknowledgment stage (payerAcceptanceStatusId of 3), it was never accepted into adjudication, so there is often nothing on file to replace. Correct it and send it as a new original (claimFreqCode of 1). Reserve replacements for claims the payer accepted. When in doubt, ask the payer which they expect.

Choosing a path

Path	Use when	Endpoint
A. Build it yourself	Your system holds the claim data and you want full control over every field.	POST /api/SharpRcm/v1/CreateClaimEdi
B. Replace a claim ClaimRev already has	The original was submitted through ClaimRev and you want to start from that claim rather than rebuild it.	POST /api/ClaimEditor/v1/CreateReplacementVoidClaim
C. Form boxes	You think in CMS-1500 / UB-04 terms and want the least amount of structure to fill in.	POST /api/ManualClaimEntry/v1/CreateClaimFromForm

All three produce an 837 that flows through the same downstream pipeline.

Path A: build the replacement yourself

This is the most direct path when your own system is the source of truth for the claim. You build a normal claim exactly as described in Submitting a Claim, and set the two replacement fields on claimEditorView.

Professional (837P) only.

POST /api/SharpRcm/v1/CreateClaimEdi
Authorization: Bearer <token>
Content-Type: application/json

{
  "claims": [
    {
      "submitterEditViewModel": { "...": "as normal" },
      "billingProviderEditorView": { "...": "as normal" },
      "subscriberEditorView": { "...": "as normal" },
      "payerEditerView": { "...": "as normal" },
      "patientEditorView": { "...": "as normal" },

      "claimEditorView": {
        "patientControlNumber": "ACCT-001",
        "totalClaimChargeAmt": "150",
        "placeOfService": "11",

        "claimFreqCode": "7",
        "refOriginalReference": {
          "qualifierCode": "F8",
          "refValue": "1234567890123"
        },

        "...": "every other claim-level field, corrected"
      },

      "serviceLinesEditorView": [ "every service line, corrected" ]
    }
  ],
  "submitterId": "YOURSUBMITTERID",
  "submitterName": "Bixby Medical Group",
  "submitterContactName": "Billing Office",
  "submitterPhone": "9185551234"
}

qualifierCode is optional

The qualifier is fixed by the X12 slot, so ClaimRev fills it in. Both of these produce REF*F8*1234567890123:

refOriginalReference	Generated EDI
{ "qualifierCode": "F8", "refValue": "1234567890123" }	REF*F8*1234567890123
{ "refValue": "1234567890123" }	REF*F8*1234567890123

The same applies to the other qualifier-bearing objects on the editor model: send dateOnSetOfCurrentIllness as { "dateValue": "20240115" } and it goes out as DTP*431*D8*20240115. Sending the qualifier explicitly is still fine, and makes the payload self-documenting. If you do send one, it must be the correct value for that slot, because ClaimRev only fills a qualifier that is missing and will not overwrite one you supplied.

Keep patientControlNumber (CLM01) the same as the original claim. It is your own identifier for the claim, and matching it on the replacement is what lets you tie the two together in reporting and in claim search afterwards.

Everything else is the standard claim body. Required blocks are claimEditorView, billingProviderEditorView, subscriberEditorView, payerEditerView, submitterEditViewModel, and at least one entry in serviceLinesEditorView. Missing blocks come back as a 400 with a per-claim message naming the field. The full shape is in the API Reference.

The response gives you the control numbers ClaimRev stamped on the EDI it built, plus the upload result:

{
  "bhtControlNumber": "SHRPRCMEDIB202609151423",
  "groupControlNumber": "142312345",
  "transactionControlNumber": "638503476520012345",
  "uploadFileResult": { "message": "...", "isError": false }
}

To send a void instead, set claimFreqCode to "8". Keep refOriginalReference and the rest of the claim exactly as it was.

Path B: replace a claim ClaimRev already has

If the original went out through ClaimRev, you can have ClaimRev build the replacement from the stored claim rather than reconstructing it. This is the same operation as the Replace/Void button in the portal, and it is fully available over the API.

Create the replacement

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

{
  "claimObjectId": "65e2f4a1c3d2b10f9a8e7d61",
  "freqCode": "7",
  "controlNumber": "1234567890123"
}

Field	Value
claimObjectId	objectId of the original claim, from claim search.
freqCode	"7" for a replacement, "8" for a void.
controlNumber	The payer control number, which becomes REF*F8.

What ClaimRev does with it:

1. Copies the stored claim and applies CLM05-3 and REF*F8.
2. Clears the payer acceptance, file acceptance, ERA, and error state so the copy starts clean.
3. Links the copy back to the original through its previous-claim references.
4. Marks the original claim as void and flags it as worked.
5. Saves the copy as a new claim with a new object id, and returns that id.

{
  "claimObjectId": "65e30b77c3d2b10f9a8e7f02",
  "claimTypeId": "1"
}

claimTypeId is 1 for professional, 2 for institutional, 3 for dental.

Send it

The replacement is parked, not sent

CreateReplacementVoidClaim leaves the new claim in Editing status (14), which is a held state. Nothing transmits it. This is deliberate, because the usual reason for a replacement is that something on the claim needs correcting. In the portal this is the point where a user opens the claim editor and makes the fix.

Over the API, load the new claim, apply your corrections, and save it with a status of 11 (Reprocess), which releases it into the send pipeline:

GET /api/ClaimEditor/v1/GetClaimForEdit?claimId=65e30b77c3d2b10f9a8e7f02
Authorization: Bearer <token>

Edit the returned FullClaimEditorViewModel, then:

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

{
  "claimId": "65e30b77c3d2b10f9a8e7f02",
  "claimStatusId": 11,
  "...": "the rest of the edited claim"
}

claimStatusId	Effect
14 (Editing)	Saves your changes and leaves the claim parked. Equivalent to Save in the portal.
11 (Reprocess)	Saves and releases the claim to be sent. Equivalent to Save & Send in the portal.

If nothing on the claim needs correcting and you only wanted the frequency code and original reference applied, you can post the claim back unchanged with claimStatusId of 11.

Both CreateReplacementVoidClaim and SaveClaimForEdit require the write:claims scope.

Path C: form boxes

If you already think in CMS-1500 or UB-04 terms, Creating a Claim from Form Boxes handles replacements with two extra fields. This path does not involve the RCM model at all, and because it is shaped by the paper form it exposes fewer fields than Path A. That is the tradeoff: less to fill in, less you can express.

CMS-1500 (professional):

{
  "cms1500": {
    "box22_ResubmissionCode": "7",
    "box22_OriginalRefNumber": "1234567890123",
    "box26_PatientAccountNumber": "ACCT-001",
    "...": "the rest of the corrected form"
  }
}

UB-04 (institutional): the frequency is the third digit of the type of bill, and the original reference is FL64.

{
  "ub04": {
    "fl04_TypeOfBill": "0117",
    "fl64_DocumentControlNumber": "1234567890123",
    "...": "the rest of the corrected form"
  }
}

If box22_ResubmissionCode is left empty, the claim goes out as an original (1).

After you send

A replacement follows exactly the same lifecycle as any other claim: parse, route, batched send, 999, 277CA, then 835. See Submitting a Claim.

Two things worth watching for:

• The replacement gets its own payer control number. If you have to replace the claim a second time, use the control number from the most recent 277CA, not the original one.
• Track both claims. With Path B the original is marked void and the replacement is a separate record with a new object id. Searching on the shared patientControlNumber (CLM01) returns both.

Common mistakes

Symptom	Cause
Payer rejects as a duplicate	Sent as claimFreqCode of 1 instead of 7.
Payer cannot match the claim	REF*F8 missing, or carrying your own CLM01 instead of the payer's control number.
Wrong qualifier in the generated EDI	A qualifierCode was sent explicitly but with the wrong value for that slot. ClaimRev fills a missing qualifier but never overwrites one you supplied.
Replacement never transmits	Path B claim left in Editing status (14) and never saved as Reprocess (11).
Service lines disappear from the payer's record	Sent only the changed lines. A replacement must carry the complete claim.
No payer control number to use	The 277CA has not arrived yet, or the claim was rejected at acknowledgment and was never on file.