Skip to main content

Data Synchronization and ID Management

To ensure seamless and accurate data processing between your systems and Paytient, it is highly critical that data identifiers (IDs) remain strictly consistent.

Whether you are creating a new employee, sending an eligibility file, processing claims, or updating payroll schedules, our system relies on the IDs you provide to correctly match external records to our internal data.

This guide outlines the core identifiers we use, why they are important, and how they must be combined to keep our systems in perfect sync.

Core Identifiers: Why They Matter​

When sending data to Paytient, you will pass several "external" IDs—these are the unique identifiers generated and used within your system. We use these external IDs to find and/or create the corresponding internal records within our system.

1. External Employer ID (Client ID)​

  • What it does: Allows us to locate the correct employer in our system.
  • Why it is important: This is the foundational ID. Without a consistent Employer/Client ID, we cannot accurately associate any subsequent employee, plan, or claims data with the correct organization.

2. External Employee ID​

  • What it does: Allows us to locate the correct individual employee within our system.
  • Why it is important: This ensures that benefits, payroll deductions, and claims are routed to the exact correct person.

The Power of ID Combinations​

While individual IDs are important, they are rarely used in isolation. Because we process data for many different partners and organizations, we rely on combinations of IDs to ensure absolute accuracy and prevent data collisions.

The Employer + Employee ID Combination​

It is entirely possible that two different employers might assign the same Employee ID to different people (e.g., "Employee 1001" exists at both Company A and Company B).

By requiring the combination of the External Employer ID and the External Employee ID, we ensure:

  • We establish the correct employer-employee relationship.
  • We accurately match your data to the unique internal Employer and Employee IDs in our system.
  • We associate claims and payroll schedule information to the correct individual, eliminating the risk of crossing data between companies.

The Comprehensive Plan Combination​

To manage specific benefit plans, we require a broader combination of data points: External Employer ID + External Employee ID + External Plan ID + External Plan Start Date + External Plan End Date.

This specific combination allows us to:

  • Accurately link a specific benefit plan to an employee for a specific timeframe.
  • Ensure that incoming claims are verified and processed against the correct, active plan year for that employee.

The Golden Rule: Total Consistency​

In order for our systems to remain in sync, these external IDs must be perfectly consistent across all interactions.

Whether data is entering our system via an Eligibility File, a Claims File, a Payroll File, or through direct API calls, the IDs must align.

For example, if an employee is established in the Eligibility File under External Employer ID ABC and External Employee ID 123, any subsequent Claims or Payroll data for that person must use those exact same identifiers. A mismatch will result in orphan records or rejected data.

Important Note Regarding the Partner API​

External vs. Internal IDs​

While our batch files (Eligibility, Claims, Payroll) utilize your External IDs to match records, the Partner API requires Paytient's Internal IDs to access specific resources.

How to Retrieve Our Internal IDs​

To interact with specific employers or employees via the Partner API, you must first query our endpoints to retrieve their Paytient-assigned id.

1. Get the Employer ID: Send a GET request to [/api/employers]. Based on your authorization token, the response will return all employers associated with your organization.

  • Action: Extract the id attribute from the relevant employer record. You will use this as a path variable in subsequent API calls.

2. Get the Employee ID: Using the employer ID retrieved in step one, send a GET request to [/api/employers/{employerId}/employees]. The response will contain all employees associated with that employer.

  • Action: Extract the id attribute from the relevant employee record.

3. Access Additional Resources: Now that you have the internal Paytient IDs for your employers and employees, you can safely use them as path variables to navigate the Partner API.

Next Steps: See the API Reference to explore all available endpoints, required parameters, and detailed request/response schemas.