Skip to main content

Claims File

This guide provides everything you need to know about submitting claims data files to Paytient for processing.

Overview​

Claims files contain adjudicated claim information from your system that allows Paytient to track employee healthcare spending and provide visibility into their out-of-pocket expenses.

What Claims Data Includes​

  • Medical and pharmacy claims
  • Employee responsibility amounts
  • Service descriptions and provider information
  • Claim adjustments and reversals
  • Plan and coverage details

Why Claims Data Matters​

Claims data enables:

  • Employee visibility - Members can see their healthcare spending
  • Account reconciliation - Accurate tracking of what employees owe
  • Financial planning - Helps employees budget for medical expenses
  • Reporting and analytics - Insights into healthcare utilization

Getting Started​

Before submitting your first claims file:

  1. Review the detailed Claims File Specification for complete field definitions
  2. Set up your SFTP connection - See SFTP Connection Setup Guide
  3. Understand security requirements - See Security & Transmission Guidelines
  4. Review file formatting rules - See General File Requirements

File Specifications Summary​

Basic Requirements​

PropertyValue
File TypeCSV with UTF-8 encoding
Filename ConventionClientID_Claims_YYYYMMDD.csv
Transmission FrequencyDaily (Monday - Friday)
Transmission MethodSFTP to sftp.paytient.com
Transmission ScheduleRecommended: After daily claim processing completes

Example Filename: ACME123_Claims_20240315.csv

Required Headers​

Your CSV file must include the following headers in the first row (order doesn't matter, but names must match exactly):

Client ID,Employee ID,Plan ID,Plan Year Start,Plan Year End,Transaction ID,Claim ID,Claim Type,Date of Service,Processing Date,Employee Responsibility,Billed Amount,Service Description,Service Category,Provider Name,Plan Network
Complete Field Specifications

For detailed field descriptions, types, formats, and examples, refer to the Claims File Specification.

Business Logic & Validation Rules​

Understanding how Paytient processes claims files will help you avoid common errors. For a comprehensive understanding of how identifiers work across all file types and API interactions, see Data Synchronization and ID Management.

Employee Matching​

How it works:

  • We use the combination of Client ID + Employee ID to identify individuals
  • This combination must match an existing employee in our system

Validation:

  • ✅ Pass: Employee exists in eligibility data → Claim is added
  • ❌ Fail: Employee does not exist → Claim is rejected

Common Issues:

  • Employee not yet loaded in eligibility file
  • Typo in Employee ID
  • Employee terminated but claims still processing
Employee Must Exist First

Claims for an employee will be rejected if that employee hasn't been loaded through an eligibility file first. Ensure employees are active in the system before submitting their claims.

Plan Matching​

How it works:

  • We use Plan ID + Plan Year Start + Plan Year End to identify unique plans
  • This combination must match plan information provided in eligibility data

Validation:

  • ✅ Pass: Plan combination exists → Claim is processed
  • ❌ Fail: Plan combination doesn't exist → Claim is rejected

Common Issues:

  • Plan dates don't match eligibility file
  • Plan ID typo or format difference
  • New plan year not yet loaded

Duplicate Prevention​

How it works:

  • We use Transaction ID to ensure each claim transaction is unique
  • Transaction IDs should be universally unique identifiers (UUIDs)

Validation:

  • ✅ Pass: Transaction ID is unique → Claim is added
  • ❌ Fail: Transaction ID already exists → Claim is rejected

Best Practice: Use UUID format for transaction IDs (e.g., 550e8400-e29b-41d4-a716-446655440000)

Claim Type Handling​

Claims can be submitted as Original, Adjustment, or Reversal:

Original Claims​

When to use: First time submitting a claim

Requirements:

  • Unique Transaction ID
  • Unique Claim ID (or first time using this Claim ID)
  • Claim Type = Original

Validation:

  • ✅ Pass: All requirements met → Claim is added

Adjustment Claims​

When to use: Modifying an existing claim (change in amounts, dates, etc.)

Requirements:

  • Unique Transaction ID (new ID, different from original)
  • Existing Claim ID (must match an existing Original claim)
  • Claim Type = Adjustment

Validation:

  • ✅ Pass: Claim ID exists → Adjustment is applied
  • ❌ Fail: Claim ID doesn't exist → Adjustment is rejected

Reversal Claims​

When to use: Completely removing/voiding a previously submitted claim

Requirements:

  • Unique Transaction ID (new ID, different from original)
  • Existing Claim ID (must match an existing Original claim)
  • Claim Type = Reversal

Validation:

  • ✅ Pass: Claim ID exists → Claim is reversed
  • ❌ Fail: Claim ID doesn't exist → Reversal is rejected
Adjustment vs Reversal
  • Adjustment: Modifies the claim (e.g., employee responsibility changed from $100 to $75)
  • Reversal: Completely removes the claim (e.g., claim was processed in error)

Data Formatting Examples​

Currency Amounts​

The Employee Responsibility and Billed Amount fields must follow specific formatting:

Correct Formatting:

100.00    ← Positive amount
-25.50    ← Negative amount (refund/reversal)
0.00      ← Zero amount
1500.00   ← Larger amount

Incorrect Formatting:

$100.00    ← No currency symbol
100        ← Must include decimals
1,500.00   ← No commas
(25.50)    ← Use minus sign, not parentheses

Dates​

All date fields use the format YYYY-MM-DD:

Correct:

2024-03-15
2024-01-01
2023-12-31

Incorrect:

03/15/2024
15-Mar-2024
2024-3-15  ← Missing leading zero

Complete Example Row​

ACME123,EMP001,PLAN-2024,2024-01-01,2024-12-31,550e8400-e29b-41d4-a716-446655440000,CLAIM-12345,Original,2024-03-10,2024-03-15,75.00,250.00,Office Visit - Annual Physical,Medical,Dr. Jane Smith - Primary Care,InNetwork

Transmission Process​

Step-by-Step File Submission​

  1. Generate your claims file following all specifications
  2. Connect to SFTP at sftp.paytient.com
  3. Upload to your designated folder
  4. Verify upload completed successfully
  5. Monitor for processing confirmation (contact your implementation team for notification setup)
  • Frequency: Daily (Monday - Friday)
  • Timing: After your daily claim adjudication process completes
  • Best Practice: Submit files at a consistent time each day
Automated Transfers

Consider automating your file generation and SFTP upload to ensure consistent, timely delivery of claims data.

Security Requirements​

Claims files contain Protected Health Information (PHI). For complete security and transmission requirements, see Security & Transmission Guidelines.

Testing Your Integration​

Before Going Live​

  1. Submit test file with sample data (masked/synthetic)
  2. Verify processing - confirm file was accepted
  3. Check results - validate claims appear correctly
  4. Test error scenarios:
    • Invalid employee
    • Duplicate transaction ID
    • Adjustment for non-existent claim
  5. Validate claim flow:
    • Original claim
    • Adjustment to that claim
    • View results in application

Ongoing Monitoring​

  • Track file submission success rates
  • Monitor rejection/error reports
  • Review processing time patterns
  • Maintain logs of file transmissions

Getting Help​

If you encounter issues with claims file processing:

  1. Review this guide and related documentation
  2. Check error messages for specific guidance
  3. Verify against Claims File Specification
  4. Contact your Paytient implementation team with:
    • Filename and submission timestamp
    • Specific error messages received
    • Sample data (first 5 rows with PHI removed)
    • Steps already attempted

Next Steps​

  1. Review the Claims File Specification
  2. Set up your SFTP connection
  3. Generate and test a sample claims file
  4. Submit your first production file
  5. Monitor results and establish regular transmission schedule
  6. Set up processing for the Claims Response File Paytient sends back after each submission