Claim Responses

The Oystehr RCM Service produces several pieces of feedback over the lifetime of a claim. These take the form of ClaimResponse resources, and the content will differ based on claim adjudication.

Relationship to `Claim` Resources

Each ClaimResponse will have a reference to the originating Claim, with a use of claim:

{
  resourceType: "ClaimResponse",
  use: "claim"
  request: {
    reference: 'Claim/...' // internal FHIR reference to Claim
  }
}

Response Types

ClaimResponse resources are created at three key points in the claim adjudication process:

as an initial response to the claim submission request
when the status of the claim is updated by the clearinghouse (or by a manual call by you to the set-claim-status endpoint (opens in a new tab))
when an ERA is received from the payer

These can be differentiated by looking at the tags of the ClaimResponse. Each resource will have a tag with system https://tags.fhir.oystehr.com/rcm-claim-response-type, with the code and display values indicating the type. Valid codes are submission-response, status-update , and era.

Claim Submission Responses

When submitting a claim, the Oystehr RCM Service generates a ClaimResponse, saves it to your FHIR datastore, and returns it in the response body.

The ClaimResponse.outcome field will denote whether the claim was accepted or if the clearinghouse encountered an error while processing the claim for submission to the payer. For example, a failed submission will look like this:

{
  resourceType: "ClaimResponse",
  status: "active",
  outcome: "error",
  error: [
    {
      code: {
        text: "Some error in the clearinghouse",
      },
    },
  ],
  type: {
    coding: [
      {
        system: "http://terminology.hl7.org/CodeSystem/claim-type",
        code: "professional",
      },
    ],
  },
  created: "2026-01-01T00:00:00Z",
  use: "claim",
  patient: {
    reference: "Patient/...",
  },
  request: {
    reference: "Claim/...",
  },
  insurer: {
    reference: "https://rcm-api.zapehr.com/v1/payer/12345",
  },
  meta: {
    tag: [{
      system: "https://tags.fhir.oystehr.com/rcm-claim-response-type",
      code: "submission-response",
      display: "Submission Response"
    }]
  },
  // ...
}

Claim Status Updates

After a claim is accepted by the clearinghouse, it is submitted to the payer. The payer will send a notification containing either an acceptance of a rejection of the claim submission. When the Oystehr RCM Service receives this notification, it will create a ClaimResponse containing the new status information, and any errors that led to the rejection.

The ClaimResponse.outcome field will denote whether the claim was accepted by the payer or if there were errors that need to be addressed before the claim can be adjudicated. For example, a rejected claim will look like this:

{
  resourceType: "ClaimResponse",
  status: "active",
  outcome: "error",
  error: [
    {
      code: {
        text: "An error reported by the payer",
      },
    },
  ],
  type: {
    coding: [
      {
        system: "http://terminology.hl7.org/CodeSystem/claim-type",
        code: "professional",
      },
    ],
  },
  created: "2026-01-01T00:00:00Z",
  use: "claim",
  patient: {
    reference: "Patient/...",
  },
  request: {
    reference: "Claim/...",
  },
  insurer: {
    reference: "https://rcm-api.zapehr.com/v1/payer/12345",
  },
  meta: {
    tag: [{
      system: "https://tags.fhir.oystehr.com/rcm-claim-response-type",
      code: "status-update",
      display: "Status Update"
    }]
  },
  // ...
}

ERAs

Once a claim has been accepted by both the clearinghouse and payer, it is adjudicated. After adjudication, the payer sends an ERA containing payment information or a denial. The ERAs created by payers often contain information for more than one claim. The Oystehr RCM Service breaks these up into a PaymentReconciliation, which captures information about the total payment, if any, and a set of ClaimResponse resources. A Provenance resource is also created to link these resources together.

You can also upload ERAs manually using the process-era endpoint (opens in a new tab). The same logic used for ERAs received from payers is applied to any ERA you upload.

Matching ERAs to Claims

The Oystehr RCM Service uses the Oystehr-managed PCN to match the payer responses contained in ERAs to the claims you've submitted through the Oystehr RCM Service. If an ERA is received that contains adjudication information for a claim which was not submitted to the payer using the Oystehr RCM Service, it will be "unmatched." The ClaimResponse.request field will reference a contained Claim resource instead of a separate full Claim.

`ClaimResponse`

The ClaimResponse created for an ERA contains per-service-line information in its item array. This is where you will find information about adjustments, payments, and any remarks by the payer for each service line in your claim.

The status of the claim, including if it has been processed or denied, can be found in the ClaimResponse.extension field, using url https://extensions.fhir.oystehr.com/era-status-code. See here (opens in a new tab) for potential values for this field.

The payer claim control number, used for corrections and voids, is also stored as an extension; its url is https://extensions.fhir.oystehr.com/era-icn.

{
  resourceType: "ClaimResponse",
  status: "active",
  outcome: "complete",
  type: {
    coding: [
      {
        system: "http://terminology.hl7.org/CodeSystem/claim-type",
        code: "professional",
      },
    ],
  },
  created: "2026-01-01T00:00:00Z",
  use: "claim",
  patient: {
    reference: "Patient/...",
  },
  request: {
    reference: "Claim/...", // or #claim if "unmatched"
  },
  insurer: {
    reference: "https://rcm-api.zapehr.com/v1/payer/12345",
  },
  item: [
    // payment information per-service-line
  ],
  extension: [
    {
      url: "https://extensions.fhir.oystehr.com/era-status-code",
      valueString: '1', // Processed as Primary
    },
    {
      url: "https://extensions.fhir.oystehr.com/era-pcn",
      valueString: 'xxxxxx', // Oystehr-managed PCN associated with the originating Claim
    },
    {
      url: "https://extensions.fhir.oystehr.com/era-icn",
      valueString: 'yyyyyy', // Payer claim control number, used for corrections and voids
    },
    // additional optional remark codes supplied by the payer
  ],
  meta: {
    tag: [{
      system: "https://tags.fhir.oystehr.com/rcm-claim-response-type",
      code: "era",
      display: "ERA"
    }]
  },
  // if "unmatched":
  // contained: [
    // { 
      // resourceType: "Claim" 
      // id: "#claim" 
      // ...
    // }
  // ]
  // ...
}

`PaymentReconciliation`

The PaymentReconciliation created by the Oystehr RCM Service contains information on the total amount paid and the check number used in payment. It also includes the original x12 used to generate all resources.

{
  resourceType: "PaymentReconciliation",
  status: "active",
  outcome: "complete",
  paymentIdentifier: {
    system: "https://identifiers.fhir.oystehr.com/era-check-number",
    value: "12345",
  },
  paymentIssuer: {
    reference: "https://rcm-api.zapehr.com/v1/payer/12345",
  },
  paymentAmount: 200.00,
  paymentDate: "2026-01-01",
  extension: [
    {
      url: "https://extensions.fhir.oystehr.com/rcm-raw-x12",
      valueString: "...", // unformatted x12
    },
    // ...
  ],
  // ...
}

`Provenance`

The Provenance record is used to link the PaymentReconciliation and all ClaimResponse resources generated from a single ERA.

{
  resourceType: "Provenance",
  recorded: "2026-01-01T00:00:00Z",
  activity: {
    coding: [{
      system: "http://hl7.org/fhir/ValueSet/provenance-activity-type",
      code: "era-processing",
    }],
  },
  target: [
    {
      reference: "PaymentReconciliation/...",
    },
    {
      reference: "ClaimResponse/...",
    },
    {
      reference: "ClaimResponse/...",
    },
    // ...
  ],
  // ...
}

Claim Submission Eligibility