PlanSource API

The PlanSource API Developer Hub

Welcome to the PlanSource API developer hub. You'll find comprehensive guides and documentation to help you start working with PlanSource API as quickly as possible, as well as support if you get stuck. Let us help you jump right in!

SOP for Payroll Business Rules

PlanSource Payroll Business Rules are the processes and rules used when handling/processing payroll and payroll deductions. PlanSource utilizes and provides various forms of effective dating, premium deduction amounts, payroll deduction standardized codes, and deduction methods to determine an employee’s payroll deduction premium. Via the PlanSource payroll deduction API, all employee payroll deduction data will be provided for the partner to determine what best fits their system. To further understand how PlanSource handles each piece of payroll deductions, please read below under each section to find out more.

Effective Dating

Effective Dating is the way PlanSource utilizes the dates that affect payroll and payroll deduction. Below are the main data fields that can be configured by a client's HR administrator and can be retrieved by a client's developer.

  • org_plan_year_starts
  • org_plan_year_ends

These dates are used to denote the beginning and end of the current plan year. To configure the dates, log in to the PlanSource's Benefits Admin site.

  1. Click on the Configure tab.
  2. Click on the Plan Year tab.
  3. Make sure you are in the correct plan year you mean to configure, and then change the dates in the fields labeled Plan Year Starts On and Plan Year Ends On.
  4. Make sure to change the Name field to help keep things consistent.
  5. Click Save & Continue to save the configuration.
  • start_date
  • end_date

These dates can only be used with PlanSource's API to denote the date range for payroll changes. For utilization, make a GET call to either the /payroll_coverages_subscriber/{id} or /payroll_coverages_subscribers endpoint and enter the desired start and end dates into the URL (these fields are required when making the GET call). Below is an example cURL script using both dates.

curl --request GET \
  --url 'https://example.com/admin/payroll_coverages_subscribers?start_date=01-04-2018&end_date=01-03-2019'
  • termination_date

This date is created when a subscriber declines a benefit. The termination date will populate with the date that the subscriber's enrollment begins on. So if the subscriber's enrollment begins on 1/1/2018, and they decline a benefit and checkout on 1/3/2018, the termination date for that benefit would be 1/1/2018. An HR admin can also change this termination date within PlanSource's Benefits Admin site.

  1. Click the Employees tab.
  2. Search for an employee, click on their name, and click the Edit button next to one of their declined benefits.
  3. Change the date in the field labeled Termination Date.
  4. Click the Apply button to apply the changes.
  • original_effective_date
  • change_effective_date

These dates are used to describe the original effective date of a coverage and the new effective date of a coverage that changes. If a subscriber elects a benefit and never changes it, the original effective and change effective dates would be the same. If a subscriber has an original effective date of 1/1/18 and a change effective date of 1/1/18, goes to enroll in a new benefit in March of 2018, then the original date would stay the same but the change effective date would become a new date in March when the coverage becomes effective. An HR admin can also change these dates within PlanSource's Benefits Admin site (similar to changing the termination date).

  1. Click the Employees tab.
  2. Search for an employee, click on their name, and click the Edit button next to one of their elected benefits.
  3. Change the dates in the fields labeled Original Effective Date and Change Effective Date.
  4. Click the Apply button to apply the changes.
  • Coverage start date

This date denotes the eligibility period start date for a subscriber. This date is not utilized in the API, but instead is configured within PlanSource's Benefits Admin site.

  1. Click the Employees tab.
  2. Search for an employee, click on their name, and click the Edit Employee tab.
  3. Change the date for the field labeled Eligibility Period Start Date.
  4. Click the Save button to save the configuration
  • Future Dated Payroll Deduction

Another important date that PlanSource works to implement is Future Dated Payroll Deduction (FDPD). FDPD is used when a subscriber elects a change in benefit that will take effect in the future. Some payroll vendors can accept this date, and it will be stored in their system as a future effective date for the coverage to apply when the date arrives. If a payroll vendor can accept future effective dating, PlanSource has the ability to supply it.

Declining a Previously Elected Benefit

PlanSource also offers a cool feature when a subscriber decides to decline a benefit previously elected.

  • Subscriber makes an election.
  • The election is sent real time to the carriers/vendors.
  • Subscriber goes back and declines their coverage.
  • PlanSource terminates the coverage with a termination reason of "Subscriber voluntarily waived coverage".

📘

Declined Benefit Sent Through API

If a subscriber declines a benefit election during enrollment, PlanSource will send the declined data when a developer makes a GET call to the /payroll_coverages_subscriber/{id} or /payroll_coverages_subscribers endpoint. Below is an excerpt from a GET call response to the /payroll_coverages_subscriber/{id} endpoint.

{
    "benefit_name": "Medical",
    "benefit_lookup_code": "medical",
    "plan_name": "Decline",
    "coverage_level": "Decline",
    "termination_date": "2018/01/04",
    "termination_reason": "Subscriber voluntarily waived coverage",
}

Premium Deduction Amounts

Premium Deduction Amounts are the costs that subscribers and employers pay for insurance. Below are the fields (and their descriptions) that are sent back to a developer when making a GET call on a payroll endpoint.

API FieldField Description
subscriber_premiumPremium the subscriber will be paying per pay period based on the defined cost at the plan and coverage level. In the event imputed income is calculated, this will be the sum of the subscriber_pretax_premium and the subscriber_posttax_premium.
org_premiumPremium the employer will be paying per pay period.
imputed_incomeEmployee's per pay period imputed income as calculated per plan configuration.
subscriber_pretax_premiumPremium the subscriber will be paying pre-tax.
subscriber_posttax_premiumPremium the subscriber will be paying post-tax.
volumeCurrent guaranteed issued / approved volume for the specified benefit.
dp_sub_imputed_incomeThis field in summation with dp_org_imputed_income equal imputed income.
dp_org_imputed_incomeThis field in summation with dp_sub_imputed_income equal imputed income.

Payroll Schedule ID

Payroll Schedule ID's are the unique ID numbers assigned by PlanSource to a payroll schedule when created. When a new payroll schedule is created, PlanSource assigns the ID, but it is done behind the scenes. That means a developer needs to make an API GET call to the /subscriber/meta endpoint in order to retrieve the unique ID. When it comes to assigning a payroll schedule to a subscriber using API calls, the developer must use the payroll schedule ID, not its name or lookup_code. Below is an excerpt from a GET call to the /subscriber/meta endpoint.

"payroll_schedules": [
            {
                "id": 563,
                "name": "Biweekly (26 per year)",
                "lookup_code": "biweekly26_1"
            }

📘

Payroll Schedules

To learn more about Payroll Schedules, go read about them in Payroll Schedules!

Taxation Treatment

There are seven important data fields that may need explanation to someone unfamiliar with PlanSource's practice of taxation treatment.

  • benefit_lookup_code
    Benefit lookup code refers to the name of the benefit with calculations being displayed when called by the API.
  • tax_treatment
    Taxation treatment refers to the type of taxation that can affect the subscriber's and organization's premiums. There are two values that can result from tax_treatment:
    • "pretax"
    • "posttax"
  • subscriber_premium
    Subscriber premium refers to the amount a subscriber will pay per pay period for a benefit. The subscriber premium = subscriber pre-tax premium + subscriber post-tax premium.
  • subscriber_pretax_premium
    Subscriber pre-tax premium refers to the amount a subscriber will pay per pay period for a benefit pre-tax.
  • subscriber_posttax_premium
    Subscriber post-tax premium refers to the amount a subscriber will pay per pay period for a benefit post-tax.
  • org_premium
    Organization premium refers to the amount an organization, or employer, will be paying for a specific premium per pay period.
  • imputed_income
    Imputed incomes refers to the value of a service or benefit provided by employers to employees, which must be treated as income. The actual calculated amount for imputed income is configured within PlanSource in benefit configuration. There are three options to use for calculating:
  • Employee Only Amount
  • Original Coverage Level Difference
  • Formula

How to Determine Which Subscriber Premium to Use

PlanSource's standard practice for obtaining an employee's payroll deductions via the API is to utilize the benefit_lookup_code to determine which benefit the deduction is for, the tax_treatment to determine whether the benefit is pre-tax or post-tax, and the subscriber_premium field to determine the amount per pay period the subscriber should be deducted.

In some use cases however, typically those where a domestic partner is enrolled, the standard practice may differ. In some cases the subscriber_premium field may be broken out into individual tax specific premium amounts, especially when an imputed income can be calculated. If this is the case, the best practice is to utilize the benefit_lookup_code to determine which benefit the deduction is for, the subscriber_pretax_premium to determine the amount per pay period the subscriber should be deducted pre-tax, the subscriber_posttax_premium to determine the amount per pay period the subscriber should be deducted post-tax, and the imputed_income field.

Please use the following payroll business rule flowchart to better understand which subscriber premium fields should be used:

Payroll Standardized Deduction Codes

Contained in this table is a list of all the lookup_code items for benefits currently configured for some client or another in our system. Please note that while any given client will only utilize some of the more generic lookup_code items there is a chance based on our carrier configurations that mapping will be needed for all of these items. Output will contain the benefit name, lookup_code, and premium amounts associated for an employee and their elected benefits.

Benefit NameLookup_codeEmployee_premiumEmployer_premiumImputed_incomeEmployee_pretax_premiumEmployee_post_tax_premiumVolumeSubscriber_fsa_amountOrg_fsa_amount
Medicalmedicalxxxxx
Medical 2medical_2xxxxx
Dentaldentalxxxxx
Visionvisionxxxxx
Premium FSApremium_fsaxxxxxx
Health Care Reimbursement Accounthcraxxxxxx
Dependent Care Reimbursement Accountdcraxxxxxx
Health Savings Accounthsaxxxxxx
HRAhraxxxx
Basic Employee Lifebasic_subscriber_lifexxxxxx
Basic Spouse Lifebasic_spouse_lifexxxxxx
Basic Dependent Lifebasic_dependent_lifexxxxx
Voluntary Employee Lifesubscriber_lifexxxxxx
Voluntary Spouse Lifespouse_lifexxxxxx
Voluntary Dependent Lifedependent_lifexxxxx
Basic Long Term Disabilitybltdxxxxxx
Basic Short Term Disabilitybstdxxxxxx
Voluntary Long Term Disabilityltdxxxxxx
Voluntary Short Term Disabilitystdxxxxxx
Critical Illnesscritical_illnessxxxxx
Critical Illness 2critical_illness_2xxxxx
Critical Illness 3critical_illness_3xxxxx
Basic Accidental Death or Dismembermentbasic_addxxxxx
Voluntary Accidental Death and Dismembermentaddxxxxx
Voluntary AD&D Spouse Onlyadd_spouse_onlyxxxxx
Voluntary AD&D Dependents Onlyadd_dep_onlyxxxxx
Work Related Accidentwork_accidentxxxx
Employee Assistance Programeapxxxx
Parking Reimbursement Accountparkingxxxxxx
Transit Reimbursement Accounttransitxxxxxx
Transit Reimbursement Account 2transit_2xxxxxx
Flex Creditflex_creditxxxx
Prescription Drugrxxxxxx
401(k)401kxxxx
401k Catch-Up401k_catch_upxxxx
Roth 401k401k_rothxxx
Roth 401k Catch-Up401k_roth_catch_upxxx
Cancercancerxxxx
Agreement 1agreement_1xxxx
Agreement 2agreement_2xxxx
Agreement 3agreement_3xxxx
Legallegalxxxx
Long Term Carelong_term_carexxxx
Specified Healthspecified_healthxxxx
Hospital Intensive Carehosp_intensivexxxx
Administration Feeadmin_feexxxx
Miscellaneousmiscellaneousxxxx
Accident Insuranceaccident_advance_coveragexxxx
Cancer Insurancecancer_select_plus_coveragexxxx
Critical Illness Insurancecritical_assistance_advance_coveragexxxx
Group Hospital Indemnitygroup_hospital_indemnityxxxx
PTO Purchasepto_purchasexxxxx
PTO Cash Outpto_cash_outxxxxx
Rider 1rider_1xxxx
Rider 2rider_2xxxx
Rider 3rider_3xxxx
Rider 4rider_4xxxx
Rider 5rider_5xxxx
Allstate Group Accidentallstate_grp_accidentxxxx
Allstate Group Cancerallstate_grp_cancerxxxx
Allstate Group Critical Illnessallstate_grp_critical_illxxxx
Allstate Group Disabilityallstate_grp_disabilityxxxx
Allstate Group Indemnity Medicalallstate_grp_medicalxxxx
Allstate Group Term to 100allstate_grp_term_to_100xxxx
Allstate Group Term to 100 - Childallstate_grp_term_to_100_chxxxx
Allstate Group Term to 100 - Spouseallstate_grp_term_to_100_spxxxx
Allstate Group Universal Lifeallstate_grp_univ_lifexxxx
Group Accident 1allstate_accidentxxxx
Group Cancer 2allstate_cancer2xxxx
Group Cancer 3allstate_cancerxxxx
Group Critical Illness 1allstate_critical_illness1xxxx
Group Critical Illness 2allstate_critical_illnessxxxx
Group Disabilityallstate_disabilityxxxx
Group SHOPallstate_shopxxxx
Universal Life Dependentallstate_universal_life_depxxxx
Universal Life Employeeallstate_universal_life_eexxxx
Universal Life Spouseallstate_universal_life_spxxxx
Colonial Life - Accidentcolonial_accident_0xxxx
Colonial Life - Accidentcolonial_accident_1xxxx
Colonial Life - Accidentcolonial_accident_2xxxx
Colonial Life - Cancercolonial_cancer_0xxxx
Colonial Life - Cancercolonial_cancer_1xxxx
Colonial Life - Cancercolonial_cancer_2xxxx
Colonial Life - Critical Illnesscolonial_critical_illness_2xxxx
Colonial Life - Critical Illnesscolonial_critical_illness_0xxxx
Colonial Life - Critical Illnesscolonial_critical_illness_1xxxx
Colonial Life - Dentalcolonial_dental_0xxxx
Colonial Life - Disabilitycolonial_disability_0xxxx
Colonial Life - Disabilitycolonial_disability_1xxxx
Colonial Life - Disabilitycolonial_disability_2xxxx
Colonial Life - Group Accidentcolonial_group_accident_0xxxx
Colonial Life - Group Accidentcolonial_group_accident_1xxxx
Colonial Life - Group Cancercolonial_group_cancer_0xxxx
Colonial Life - Group Cancercolonial_group_cancer_1xxxx
Colonial Life - Group Critical Illnesscolonial_group_critical_illness_0xxxx
Colonial Life - Group Disabilitycolonial_group_disability_0xxxx
Colonial Life - Group Disabilitycolonial_group_disability_1xxxx
Colonial Life - Group Hospital Confinement Indemnitycolonial_group_hospital_confinement_indemnity_0xxxx
Colonial Life - Group Hospital Confinement Indemnitycolonial_group_hospital_confinement_indemnity_2xxxx
Colonial Life - Group Hospital Confinement Indemnitycolonial_group_hospital_confinement_indemnity_1xxxx
Colonial Life - Group Specified Diseasecolonial_group_specified_disease_0xxxx
Colonial Life - Group Specified Diseasecolonial_group_specified_disease_1xxxx
Colonial Life - Group Term Lifecolonial_group_term_life_0xxxx
Colonial Life - Group Term Lifecolonial_group_term_life_1xxxx
Colonial Life - Group Term Lifecolonial_group_term_life_2xxxx
Colonial Life - Group Term Lifecolonial_group_term_life_3xxxx
Colonial Life - Hospital Confinementcolonial_hospital_confinement_0xxxx
Colonial Life - Hospital Confinementcolonial_hospital_confinement_1xxxx
Colonial Life - Intensive Carecolonial_intensive_care_0xxxx
Colonial Life - Term Lifecolonial_term_life_0xxxx
Colonial Life - Term Lifecolonial_term_life_1xxxx
Colonial Life - Term Lifecolonial_term_life_2xxxx
Colonial Life - Universal Lifecolonial_universal_life_5xxxx
Colonial Life - Universal Lifecolonial_universal_life_6xxxx
Colonial Life - Universal Lifecolonial_universal_life_7xxxx
Colonial Life - Universal Lifecolonial_universal_life_8xxxx
Colonial Life - Universal Lifecolonial_universal_life_0xxxx
Colonial Life - Universal Lifecolonial_universal_life_1xxxx
Colonial Life - Universal Lifecolonial_universal_life_2xxxx
Colonial Life - Universal Lifecolonial_universal_life_3xxxx
Colonial Life - Universal Lifecolonial_universal_life_4xxxx
Colonial Life - Whole Lifecolonial_whole_life_0xxxx
Colonial Life - Whole Lifecolonial_whole_life_1xxxx
Colonial Life Benefitscolonialxxxx
Child Interest Sensitive Whole Lifeunum_interest_sensitive_whole_life_childxxxx
Child Whole Lifeunum__whole_life_childxxxx
Employee Group Critical Illnessunum_group_critical_illness_employeexxxx
Employee Group Critical Illness EEunum_group_critical_illness_ee_employeexxxx
Employee Interest Sensitive Whole Lifeunum_interest_sensitive_whole_life_employeexxxx
Employee Whole Lifeunum__whole_life_employeexxxx
Group Accidentunum_group_accident_employeexxxx
Short Term Disabilityunum_vwb_std_employeexxxx
Spouse Group Critical Illnessunum_group_critical_illness_spousexxxx
Spouse Group Critical Illness EEunum_group_critical_illness_ee_spousexxxx
Spouse Interest Sensitive Whole Lifeunum_interest_sensitive_whole_life_spousexxxx
Spouse Whole Lifeunum__whole_life_spousexxxx
Unum Group Hospital Indemnityunum_group_hospital_indemnity_employeexxxx
Rider Accidental Death & DismembermentRider_AD&Dxxxx
Rider CancerRider_Cancerxxxx
Rider Child TermRider_Child_Termxxxx
Rider ContinuationRider_Continuationxxxx
Rider DentalRider_Dentalxxxx
Rider Long Term CareRider_Long_Term_Carexxxx
Rider MaternityRider_Maternityxxxx
Rider Mental IllnessRider_Mental_Illnessxxxx
Rider Pre Existing ConditionRider_Pre_Existing_Conditionxxxx
Rider PrescriptionRider_Prescriptionxxxx
Rider RestorationRider_Restorationxxxx
Rider SportsRider_Sportsxxxx
Rider Spouse TermRider_Spouse_Termxxxx
Rider Subscriber TermRider_Subscriber_Termxxxx
Rider Terminal IllnessRider_Terminal_Illnessxxxx
Rider TerrorismRider_Terrorismxxxx
Rider VisionRider_Visionxxxx
Rider Waiver of PremiumRider_Waiver_of_Premiumxxxx

Updated about a year ago

SOP for Payroll Business Rules


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.