Claims Response File

This guide provides everything you need to know about receiving and processing the claims response files that Paytient sends back to you after processing your submitted claims data.

Overview

After Paytient processes your claims file submission, we generate and deliver a claims response file to your SFTP directory. This file reports the outcome of each claim processed — specifically, any claims that failed to process and the reasons why. Successfully processed claims are not included as individual rows; instead, the footer summarizes total counts.

What the Claims Response File Contains

• A header row with the file generation date
• Zero or more detail rows for failed claims only, each containing the original claim row and the failure reason
• A footer row summarizing total processed, successful, and failed record counts

Why the Claims Response File Matters

The claims response file enables you to:

• Identify and correct errors — Understand exactly why a claim failed so you can fix and resubmit it
• Reconcile submissions — Confirm how many claims were successfully processed vs. rejected
• Maintain data integrity — Ensure all intended claims are ultimately reflected in Paytient's system
• Monitor quality — Track error trends over time to improve upstream data quality

Getting Started

Before your first claims file submission:

1. Review the detailed Claims Response File Specification for complete file structure and error code definitions
2. Set up your SFTP connection — See SFTP Connection Setup Guide
3. Understand security requirements — See Security & Transmission Guidelines
4. Review general file formatting rules — See General File Requirements

File Specifications Summary

Basic Requirements

Property	Value
File Type	Pipe-delimited text
Delimiter	Pipe (|)
Has Column Headers	No
Extension	.csv
Direction	Paytient → Partner (we send, you receive)

Response File Timing

Paytient generates the response file after completing processing of your submitted claims file. Delivery timing will be coordinated during your implementation onboarding.

Example Response Filename: ClaimsResponse_ACME123_20240315.csv

Row Structure Summary

Row Type	Count	Description
Header	1	File generation date in H{YYYYMMDD} format
Detail	0 or more	One row per failed claim only
Footer	1	Totals: processed, successful, and failed counts

No News Is Good News

If the response file contains only a header and footer with zero detail rows, all of your submitted claims were processed successfully.

Reading the Response File

Header Row

The header row identifies when the response file was generated.

Format: H{YYYYMMDD}

Example:

H20260101

This means the file was generated on January 1, 2026.

Detail Rows (Failed Claims)

Each detail row represents a claim from your submission that failed to process. Detail rows are only present when failures occur.

Format: {original claim row content}|{failure reason code}

Example:

CLIENT-12345,EMPLOYEE-12345,PLAN-12345,...|InvalidClaimType

The first field contains the entire original row as you submitted it (verbatim), and the second field contains a failure reason code explaining why it was rejected.

Footer Row

The footer summarizes the overall processing outcome for your submission.

Format: T{totalProcessed}|{totalSuccess}|{totalFailed}

Example:

T25|24|1

This means 25 claims were processed, 24 succeeded, and 1 failed.

Complete File Example

H20260101
CLIENT-12345,EMPLOYEE-12345,PLAN-12345,...|InvalidClaimType
T25|24|1

Failure Reason Codes

When a claim fails, the detail row includes one of the following reason codes. Use these codes to diagnose and correct issues in your data before resubmitting.

Reason Code	Description	Common Fix
DuplicateClaim	A claim with this Claim ID already exists as an Original	Use a new, unique Claim ID or submit as an Adjustment
DuplicateTransactionId	The Transaction ID was already used in a prior submission	Generate a new unique UUID for each transaction
PlanNotFound	The Plan ID + Plan Year combination doesn't exist	Verify Plan ID and plan year dates match the eligibility file
ClaimNotFound	Adjustment or Reversal references a Claim ID that doesn't exist	Ensure the original claim was accepted before submitting adjustments or reversals
ClientAndEmployeeNotFound	The Client ID + Employee ID combination doesn't exist	Confirm the employee is active in eligibility data
EmployeeNotOnboarded	The employee exists but hasn't completed onboarding	Wait for employee onboarding to complete or contact your implementation team
MaxOutOfPocketExceeded	The claim amount exceeds the employee's maximum out-of-pocket	Verify amount accuracy; contact support if the claim is correct
NoOriginalClaim	A Reversal was submitted but no Original claim exists	Verify the original Claim ID; ensure it was accepted previously
SystemError	An unexpected system error occurred during processing	Resubmit the claim; contact Paytient support if the error persists
InvalidClaimType	The Claim Type value is not Original, Adjustment, or Reversal	Correct the Claim Type field to a valid value
InvalidTransactionId	The Transaction ID is not a valid UUID format	Ensure the Transaction ID follows UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000)
InvalidPlanNetwork	The Plan Network value is not InNetwork or OutOfNetwork	Correct the Plan Network field to a valid value
InvalidClientId	The Client ID field is empty or malformed	Provide a non-empty, valid Client ID
InvalidEmployeeId	The Employee ID field is empty or malformed	Provide a non-empty, valid Employee ID
InvalidPlanId	The Plan ID field is empty or malformed	Provide a non-empty, valid Plan ID
InvalidClaimNumber	The Claim ID field is empty or malformed	Provide a non-empty, valid Claim ID
InvalidPlanYearStartDate	The Plan Year Start date is missing or not in YYYY-MM-DD format	Reformat the date to YYYY-MM-DD
InvalidPlanYearEndDate	The Plan Year End date is missing or not in YYYY-MM-DD format	Reformat the date to YYYY-MM-DD
InvalidDateOfService	The Date of Service is missing or not in YYYY-MM-DD format	Reformat the date to YYYY-MM-DD
InvalidProcessingDate	The Processing Date is missing or not in YYYY-MM-DD format	Reformat the date to YYYY-MM-DD
InvalidPatientResponsibility	The Employee Responsibility amount is missing or not a valid decimal	Provide a valid decimal amount (e.g., 75.00 or -25.50)
InvalidBilledAmount	The Billed Amount is missing or not a valid decimal	Provide a valid decimal amount (e.g., 250.00)
InvalidServiceDescription	The Service Description field is empty	Provide a non-empty service description
InvalidServiceCategory	The Service Category is not Medical or Pharmacy	Correct the Service Category to a valid value
InvalidProviderName	The Provider Name field is empty	Provide a non-empty provider name

Processing Your Response File

Step-by-Step Workflow

1. Download the response file from your designated SFTP directory
2. Parse the footer row to get totals — confirm {totalProcessed} matches your submitted record count
3. Check for detail rows — if none are present, all claims succeeded and no action is needed
4. Extract failed claim rows from the detail section
5. Identify the failure reason from the second pipe-delimited field on each detail row
6. Correct the underlying data using the reason code guidance above
7. Resubmit corrected claims in your next claims file

Reconciliation Best Practice

Compare the footer totals against your internal records:

Footer Field	What to Verify
totalProcessed	Matches the number of data rows you submitted
totalSuccess	Matches your expected successful submissions
totalFailed	Matches the number of detail rows in the file

Resubmit Failed Claims Promptly

Failed claims are not automatically retried. You must correct the data and include the corrected claims in a future submission. Delays in resubmitting may result in missing or incomplete claims history for affected employees.

Automating Response File Processing

We recommend automating the ingestion of response files to minimize manual effort and reduce resubmission delays.

Suggested Automation Steps

1. Poll your SFTP directory for new response files after your expected processing window
2. Parse and validate the file structure (header, detail rows, footer)
3. Reconcile totals in the footer against your submission log
4. Log failed claims into an error queue or ticketing system
5. Trigger alerts if the failure rate exceeds a defined threshold
6. Auto-correct and requeue claims where the failure reason can be resolved programmatically (e.g., InvalidTransactionId → generate new UUID)

Consistent Monitoring

Setting up automated alerts for elevated failure rates helps you identify upstream data quality issues early — before they affect large numbers of employees.

Security Requirements

Claims response files contain Protected Health Information (PHI). Apply the same security controls for receiving files as you do for sending them. For complete security and transmission requirements, see Security & Transmission Guidelines.

Testing Your Integration

Before Going Live

1. Request a test response file from your Paytient implementation team with sample failed and successful rows
2. Verify parsing — confirm your system correctly splits each detail row on the pipe delimiter
3. Validate footer totals — confirm your reconciliation logic matches the summary counts
4. Test error handling scenarios:
   • Response file with zero detail rows (all claims succeeded)
   • Response file with multiple different failure reason codes
   • Response file with a high failure count
5. End-to-end test:
   • Submit a claims file with intentional errors
   • Receive and parse the response
   • Correct errors and resubmit
   • Verify corrected claims are accepted in the next response

Ongoing Monitoring

• Track failure rate per submission (target < 1%)
• Monitor for recurring failure reason codes
• Maintain an audit trail of all response files received
• Alert on missing response files (file not received within expected window)

Getting Help

If you encounter issues with claims response files:

1. Review this guide and the Claims Response File Specification
2. Check the failure reason code in the detail row for specific guidance
3. Verify your claims submission against the Claims File Integration Guide and Claims File Specification
4. Contact your Paytient implementation team with:
   • Response filename and date received
   • Specific failure reason codes encountered
   • Sample failed rows (with PHI removed)
   • Steps already attempted

Related Documentation

• Claims Response File Specification — Complete file structure and error code definitions
• Claims File Integration Guide — How to submit the claims files that generate these responses
• Data Synchronization and ID Management — Understanding identifier consistency
• Security & Transmission Guidelines — How to securely handle files
• SFTP Connection Setup Guide — Configure your SFTP connection
• General File Requirements — Common formatting rules

Next Steps

1. Review the Claims Response File Specification
2. Set up your SFTP connection to receive files from Paytient
3. Build or configure your response file parser
4. Test end-to-end with a sample file from your implementation team
5. Establish automated monitoring and alerting for ongoing submissions