Skip to main content

Eligibility File

This guide provides everything you need to know about submitting eligibility data files to Paytient for employee enrollment and account management.

Overview​

Eligibility files contain employee demographic and enrollment information that establishes employee accounts in the Paytient system and keeps their information up to date.

What Eligibility Data Includes​

  • Employee demographics (name, address, contact info)
  • Social Security Numbers and birth dates
  • Plan enrollment details
  • Credit limits and product types
  • Dependent counts

Why Eligibility Data Matters​

Eligibility data enables:

  • Account creation - New employees can access Paytient services
  • Profile updates - Keep employee information current
  • Claims validation - Ensure claims can be matched to employees
  • Plan tracking - Link employees to their health plans

Getting Started​

Before submitting your first eligibility file:

  1. Review the detailed Eligibility 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_Eligibility_YYYYMMDD.csv
Transmission FrequencyWeekly
Transmission MethodSFTP to sftp.paytient.com
Transmission ScheduleRecommended: After weekly payroll processing

Example Filename: ACME123_Eligibility_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,First Name,Last Name,Birth Date,Address 1,Address 2,City,State,ZIP Code,Email Address,Phone Number,Credit Limit,Product Type,SSN,Dependent Count
Complete Field Specifications

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

Business Logic & Validation Rules​

Understanding how Paytient processes eligibility files will help you avoid common errors.

Employee Matching & Updates​

How it works:

  • We use the combination of Client ID + Employee ID to identify unique individuals
  • This combination determines whether to create a new profile or update an existing one

Logic:

  • ✅ Employee Exists: All profile information is updated with new values
  • ✅ Employee Doesn't Exist: A new employee profile is created

What This Means:

  • Initial file submission creates all employee accounts
  • Subsequent files update existing accounts and add new employees
  • To remove an employee, simply exclude them from the eligibility file
ID Matching Rules

For detailed information on how identifiers work across eligibility and claims files, see the Data Synchronization and ID Management Guide.

Automatic Updates

Every time you submit an eligibility file, existing employees will have their information updated to match the new file. This ensures addresses, phone numbers, and other details stay current.

Unique Identifier Requirements​

Certain fields must be unique across all individuals in the system:

Email Addresses​

Rule: Each email address must belong to only one employee

Validation:

  • ✅ Pass: Email not used by another employee → Accepted
  • ❌ Fail: Email already assigned to different employee → Rejected

Phone Numbers​

Rule: Each phone number must belong to only one employee

Validation:

  • ✅ Pass: Phone number not used by another employee → Accepted
  • ❌ Fail: Phone number already assigned to different employee → Rejected

Common Issues:

  • Household landline shared by family members
  • Using company main number
  • Including extensions or country codes

Best Practice: Use personal mobile numbers unique to each employee

Format Requirements:

  • 10 digits only
  • No country code, area code separators, or extensions
  • Example: 5555555555 (not +1-555-555-5555 or 5555555555 ext. 123)

Conditional Field Requirements​

Some fields are required only in specific scenarios:

Plan ID​

Required when: Product Type = Fully Integrated Financing

Optional when: Product Type = Card Based

Why: Fully integrated financing requires linking to a specific health plan for claims processing

Plan Year End​

Required when: Product Type = Fully Integrated Financing

Optional when: Product Type = Card Based

Why: Complete plan year date range is needed for proper claims validation in fully integrated financing products

Product Types​

The system supports two product types:

Card Based​

Description: Standalone product not integrated with insurance claims

Requirements:

  • All standard fields required
  • Plan ID optional
  • Credit Limit represents available spending amount

Fully Integrated Financing​

Description: Product integrated with insurance claims processing

Requirements:

  • All standard fields required
  • Plan ID required (must match claims file Plan IDs)
  • Credit Limit represents Maximum Out-of-Pocket (MOOP) from health plan

Valid Values in CSV:

  • CARD_BASED
  • FULLY_INTEGRATED_FINANCING

Data Formatting Examples​

Personal Information​

Names:

First Name: John
Last Name: Smith-Jones  ← Hyphens are fine

Birth Date:

1990-01-15  ← Format: YYYY-MM-DD

SSN:

123456789  ← 9 digits, no hyphens or spaces

Address Information​

Addresses:

Address 1: 123 Main Street
Address 2: Apt 4B          ← Optional
City: Nashville
State: TN                  ← 2-letter code
ZIP Code: 37203            ← 5 digits, digits only

State Codes:

✅ Correct: TN, NY, CA
❌ Incorrect: Tennessee, Tenn, tn

Contact Information​

Email:

✅ Correct: john.smith@example.com
❌ Incorrect: john smith@example.com  ← No spaces
❌ Incorrect: john@                    ← Incomplete

Phone:

✅ Correct: 5555555555
❌ Incorrect: (555) 555-5555
❌ Incorrect: 555-555-5555
❌ Incorrect: +1 555 555 5555
❌ Incorrect: 5555555555 x123  ← No extensions

Numeric Fields​

Credit Limit:

✅ Correct: 5000, 1500, 500
❌ Incorrect: $5000, 5,000, 5000.00

Dependent Count:

✅ Correct: 0, 1, 2, 3
❌ Incorrect: None, N/A, (blank)

Note: If missing, system assumes 0 dependents

Plan Information​

Plan Dates:

Plan Year Start: 2024-01-01
Plan Year End: 2024-12-31

Complete Example Row​

ACME123,EMP001,PLAN-2024,2024-01-01,2024-12-31,John,Smith,1990-01-15,123 Main Street,Apt 4B,Nashville,TN,37203,john.smith@example.com,5555555555,5000,FULLY_INTEGRATED_FINANCING,123456789,2

Transmission Process​

Step-by-Step File Submission​

  1. Generate your eligibility 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: Weekly
  • Timing: After weekly payroll/HR system updates
  • Best Practice: Submit on the same day each week for consistency

Common Schedules:

  • After weekly payroll run (Monday/Tuesday)
  • End of week HR updates (Friday)
  • Following benefit administration changes
New Hire Onboarding

For time-sensitive new hires, you may submit ad-hoc files between regular weekly submissions. This ensures new employees can access Paytient services immediately.

Security Requirements​

Eligibility files contain Personally Identifiable Information (PII). 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 profiles - validate employees created correctly
  4. Test update scenario:
    • Submit initial file
    • Modify employee data
    • Submit updated file
    • Verify changes applied
  5. Test new employee:
    • Add employee to file
    • Submit
    • Verify new profile created

Ongoing Monitoring​

  • Track file submission success rates
  • Monitor rejection/error reports
  • Review duplicate email/phone warnings
  • Maintain logs of file transmissions
  • Verify employee counts match expectations

Getting Help​

If you encounter issues with eligibility file processing:

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

Next Steps​

  1. Review the Eligibility File Specification
  2. Set up your SFTP connection
  3. Generate and test a sample eligibility file
  4. Submit your first production file
  5. Establish regular weekly transmission schedule
  6. Set up claims file integration if applicable
  7. Review the Claims Response File Integration Guide to handle Paytient's processing feedback