Skip to main content

General File Requirements

This guide outlines the common technical requirements that apply to all data files transmitted to Paytient, including eligibility and claims files.

File Format Specifications​

All files must adhere to the following technical specifications to ensure proper processing:

File Type & Structure​

RequirementValueDescription
FormatCSV (Comma Separated Values)Plain text format with comma-delimited fields
EncodingUTF-8Standard encoding for handling special characters in names and addresses
Line EndingsLF or CRLFUnix (LF) or Windows (CRLF) line endings are both acceptable
Header RowRequiredFirst row must contain field names exactly as specified
DelimiterComma (,)Fields must be separated by commas
Text QualifierDouble quotes (")Use when field values contain commas or line breaks

Character Encoding (UTF-8)​

UTF-8 encoding is required to properly handle:

  • International characters (é, ñ, ö, etc.)
  • Special symbols and punctuation
  • Emoji (though not recommended in formal data)
Encoding Verification

Most modern text editors and programming languages default to UTF-8. If you're unsure, check your export settings or file properties.

Header Row Requirements​

The first row of every file must be a header row containing the exact field names as specified in the file specification.

Example Header Row:

Client ID,Employee ID,First Name,Last Name,Birth Date,Email Address
Case Sensitivity and Spacing

Field names are case-sensitive and spacing must match the specification exactly. Client ID is correct, client id, ClientID, or Client ID (extra space) will cause processing errors.

Data Formatting Standards​

Numeric Values​

Currency & Dollar Amounts:

  • check_circle Correct: 100.00 or 1500.50 or -25.00
  • cancel Incorrect: $100.00 or 1,500.50 or (25.00)

Rules:

  • No currency symbols ($)
  • No thousand separators (,)
  • Use decimal point (.) for cents
  • For decimal currency fields (e.g., claims amounts), always include exactly two decimal places
  • For fields defined as integer dollar amounts in a specific file spec (e.g., Credit Limit in the Eligibility File), do not include decimal places and follow that file's definition

Whole Numbers (IDs, Phone Numbers, ZIP Codes):

  • check_circle Correct: 12345 or 5555555555
  • cancel Incorrect: 12,345 or (555) 555-5555

Rules:

  • No formatting characters
  • No spaces or special characters
  • Digits only

Date Values​

Format: YYYY-MM-DD (ISO 8601 standard)

Examples:

  • check_circle 2024-01-15
  • check_circle 2023-12-31
  • cancel 01/15/2024 - Wrong format
  • cancel 15-Jan-2024 - Wrong format
  • cancel 2024-1-15 - Missing leading zero

Rules:

  • Four-digit year
  • Two-digit month (01-12)
  • Two-digit day (01-31)
  • Use hyphens (-) as separators

Address Values​

State Codes:

  • Use standard 2-letter state abbreviations
  • check_circle Correct: NY, CA, TX, TN
  • cancel Incorrect: New York, Calif, n.y.

Rules:

  • Uppercase letters only
  • No periods or spaces

Text Values​

Rules:

  • Trim leading and trailing whitespace
  • Avoid line breaks within fields (use text qualifiers if necessary)
  • Use standard ASCII characters when possible
  • Special characters should be properly escaped in CSV format

Text Qualifier Usage:

When a field contains commas or quotes, wrap it in double quotes:

"Smith, John","123 Main St, Apt 4"

File Naming Conventions​

Each file type has a specific naming convention to follow:

Pattern: ClientID_FileType_YYYYMMDD.csv

Examples:

  • ACME123_Eligibility_20240315.csv
  • ACME123_Claims_20240315.csv

Rules:

  • Replace ClientID with your assigned client identifier
  • Use exact file type names: Eligibility or Claims
  • Date format: YYYYMMDD (no hyphens or slashes)
  • Must end with .csv extension
warning

Files that don't follow the naming convention may not be processed automatically.

Common Issues & Solutions​

Issue: "Invalid UTF-8 encoding"​

Cause: File saved with wrong character encoding

Solution:

  • Re-save file with UTF-8 encoding
  • Most CSV export tools have an encoding option
  • Excel: Save As → CSV UTF-8 (Comma delimited)

Issue: "Header row mismatch"​

Cause: Field names don't match specification exactly

Solution:

  • Compare your headers to the specification
  • Check for typos, extra spaces, or case differences
  • Don't add or remove any fields

Issue: "Invalid date format"​

Cause: Dates not in YYYY-MM-DD format

Solution:

  • Reformat dates to ISO 8601 standard (YYYY-MM-DD)
  • Check for missing leading zeros
  • Verify month and day are valid (e.g., month 13 is invalid)

Issue: "Numeric parsing error"​

Cause: Currency or numeric fields contain formatting characters

Solution:

  • Remove all $, ,, (), and other formatting
  • Use . for decimals, - for negative numbers
  • Ensure consistent decimal places

File Validation Checklist​

Before submitting any file, verify:

  • File is saved as CSV format with UTF-8 encoding
  • First row contains the exact header names from specification
  • File follows naming convention: ClientID_FileType_YYYYMMDD.csv
  • All required fields are populated (no blank values)
  • Dates are formatted as YYYY-MM-DD
  • Numeric values have no formatting characters ($, commas)
  • State codes are 2-letter uppercase abbreviations
  • No trailing commas or blank rows at the end of file
  • File is transmitted via secure SFTP, not email

Need Help?​

If you're experiencing file formatting issues:

  1. Review the file specification for your specific file type
  2. Use the validation checklist above
  3. Contact your Paytient implementation team with:
    • Sample file (first 5 rows with sensitive data removed)
    • Specific error messages received
    • Steps you've already tried