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 Field
Field Description

subscriber_premium

Premium 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_premium

Premium the employer will be paying per pay period.

imputed_income

Employee's per pay period imputed income as calculated per plan configuration.

subscriber_pretax_premium

Premium the subscriber will be paying pre-tax.

subscriber_posttax_premium

Premium the subscriber will be paying post-tax.

volume

Current guaranteed issued / approved volume for the specified benefit.

dp_sub_imputed_income

This field in summation with dp_org_imputed_income equal imputed income.

dp_org_imputed_income

This 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 Name
Lookup_code
Employee_premium
Employer_premium
Imputed_income
Employee_pretax_premium
Employee_post_tax_premium
Volume
Subscriber_fsa_amount
Org_fsa_amount

Medical

medical

x

x

x

x

x

Medical 2

medical_2

x

x

x

x

x

Dental

dental

x

x

x

x

x

Vision

vision

x

x

x

x

x

Premium FSA

premium_fsa

x

x

x

x

x

x

Health Care Reimbursement Account

hcra

x

x

x

x

x

x

Dependent Care Reimbursement Account

dcra

x

x

x

x

x

x

Health Savings Account

hsa

x

x

x

x

x

x

HRA

hra

x

x

x

x

Basic Employee Life

basic_subscriber_life

x

x

x

x

x

x

Basic Spouse Life

basic_spouse_life

x

x

x

x

x

x

Basic Dependent Life

basic_dependent_life

x

x

x

x

x

Voluntary Employee Life

subscriber_life

x

x

x

x

x

x

Voluntary Spouse Life

spouse_life

x

x

x

x

x

x

Voluntary Dependent Life

dependent_life

x

x

x

x

x

Basic Long Term Disability

bltd

x

x

x

x

x

x

Basic Short Term Disability

bstd

x

x

x

x

x

x

Voluntary Long Term Disability

ltd

x

x

x

x

x

x

Voluntary Short Term Disability

std

x

x

x

x

x

x

Critical Illness

critical_illness

x

x

x

x

x

Critical Illness 2

critical_illness_2

x

x

x

x

x

Critical Illness 3

critical_illness_3

x

x

x

x

x

Basic Accidental Death or Dismemberment

basic_add

x

x

x

x

x

Voluntary Accidental Death and Dismemberment

add

x

x

x

x

x

Voluntary AD&D Spouse Only

add_spouse_only

x

x

x

x

x

Voluntary AD&D Dependents Only

add_dep_only

x

x

x

x

x

Work Related Accident

work_accident

x

x

x

x

Employee Assistance Program

eap

x

x

x

x

Parking Reimbursement Account

parking

x

x

x

x

x

x

Transit Reimbursement Account

transit

x

x

x

x

x

x

Transit Reimbursement Account 2

transit_2

x

x

x

x

x

x

Flex Credit

flex_credit

x

x

x

x

Prescription Drug

rx

x

x

x

x

x

401(k)

401k

x

x

x

x

401k Catch-Up

401k_catch_up

x

x

x

x

Roth 401k

401k_roth

x

x

x

Roth 401k Catch-Up

401k_roth_catch_up

x

x

x

Cancer

cancer

x

x

x

x

Agreement 1

agreement_1

x

x

x

x

Agreement 2

agreement_2

x

x

x

x

Agreement 3

agreement_3

x

x

x

x

Legal

legal

x

x

x

x

Long Term Care

long_term_care

x

x

x

x

Specified Health

specified_health

x

x

x

x

Hospital Intensive Care

hosp_intensive

x

x

x

x

Administration Fee

admin_fee

x

x

x

x

Miscellaneous

miscellaneous

x

x

x

x

Accident Insurance

accident_advance_coverage

x

x

x

x

Cancer Insurance

cancer_select_plus_coverage

x

x

x

x

Critical Illness Insurance

critical_assistance_advance_coverage

x

x

x

x

Group Hospital Indemnity

group_hospital_indemnity

x

x

x

x

PTO Purchase

pto_purchase

x

x

x

x

x

PTO Cash Out

pto_cash_out

x

x

x

x

x

Rider 1

rider_1

x

x

x

x

Rider 2

rider_2

x

x

x

x

Rider 3

rider_3

x

x

x

x

Rider 4

rider_4

x

x

x

x

Rider 5

rider_5

x

x

x

x

Allstate Group Accident

allstate_grp_accident

x

x

x

x

Allstate Group Cancer

allstate_grp_cancer

x

x

x

x

Allstate Group Critical Illness

allstate_grp_critical_ill

x

x

x

x

Allstate Group Disability

allstate_grp_disability

x

x

x

x

Allstate Group Indemnity Medical

allstate_grp_medical

x

x

x

x

Allstate Group Term to 100

allstate_grp_term_to_100

x

x

x

x

Allstate Group Term to 100 - Child

allstate_grp_term_to_100_ch

x

x

x

x

Allstate Group Term to 100 - Spouse

allstate_grp_term_to_100_sp

x

x

x

x

Allstate Group Universal Life

allstate_grp_univ_life

x

x

x

x

Group Accident 1

allstate_accident

x

x

x

x

Group Cancer 2

allstate_cancer2

x

x

x

x

Group Cancer 3

allstate_cancer

x

x

x

x

Group Critical Illness 1

allstate_critical_illness1

x

x

x

x

Group Critical Illness 2

allstate_critical_illness

x

x

x

x

Group Disability

allstate_disability

x

x

x

x

Group SHOP

allstate_shop

x

x

x

x

Universal Life Dependent

allstate_universal_life_dep

x

x

x

x

Universal Life Employee

allstate_universal_life_ee

x

x

x

x

Universal Life Spouse

allstate_universal_life_sp

x

x

x

x

Colonial Life - Accident

colonial_accident_0

x

x

x

x

Colonial Life - Accident

colonial_accident_1

x

x

x

x

Colonial Life - Accident

colonial_accident_2

x

x

x

x

Colonial Life - Cancer

colonial_cancer_0

x

x

x

x

Colonial Life - Cancer

colonial_cancer_1

x

x

x

x

Colonial Life - Cancer

colonial_cancer_2

x

x

x

x

Colonial Life - Critical Illness

colonial_critical_illness_2

x

x

x

x

Colonial Life - Critical Illness

colonial_critical_illness_0

x

x

x

x

Colonial Life - Critical Illness

colonial_critical_illness_1

x

x

x

x

Colonial Life - Dental

colonial_dental_0

x

x

x

x

Colonial Life - Disability

colonial_disability_0

x

x

x

x

Colonial Life - Disability

colonial_disability_1

x

x

x

x

Colonial Life - Disability

colonial_disability_2

x

x

x

x

Colonial Life - Group Accident

colonial_group_accident_0

x

x

x

x

Colonial Life - Group Accident

colonial_group_accident_1

x

x

x

x

Colonial Life - Group Cancer

colonial_group_cancer_0

x

x

x

x

Colonial Life - Group Cancer

colonial_group_cancer_1

x

x

x

x

Colonial Life - Group Critical Illness

colonial_group_critical_illness_0

x

x

x

x

Colonial Life - Group Disability

colonial_group_disability_0

x

x

x

x

Colonial Life - Group Disability

colonial_group_disability_1

x

x

x

x

Colonial Life - Group Hospital Confinement Indemnity

colonial_group_hospital_confinement_indemnity_0

x

x

x

x

Colonial Life - Group Hospital Confinement Indemnity

colonial_group_hospital_confinement_indemnity_2

x

x

x

x

Colonial Life - Group Hospital Confinement Indemnity

colonial_group_hospital_confinement_indemnity_1

x

x

x

x

Colonial Life - Group Specified Disease

colonial_group_specified_disease_0

x

x

x

x

Colonial Life - Group Specified Disease

colonial_group_specified_disease_1

x

x

x

x

Colonial Life - Group Term Life

colonial_group_term_life_0

x

x

x

x

Colonial Life - Group Term Life

colonial_group_term_life_1

x

x

x

x

Colonial Life - Group Term Life

colonial_group_term_life_2

x

x

x

x

Colonial Life - Group Term Life

colonial_group_term_life_3

x

x

x

x

Colonial Life - Hospital Confinement

colonial_hospital_confinement_0

x

x

x

x

Colonial Life - Hospital Confinement

colonial_hospital_confinement_1

x

x

x

x

Colonial Life - Intensive Care

colonial_intensive_care_0

x

x

x

x

Colonial Life - Term Life

colonial_term_life_0

x

x

x

x

Colonial Life - Term Life

colonial_term_life_1

x

x

x

x

Colonial Life - Term Life

colonial_term_life_2

x

x

x

x

Colonial Life - Universal Life

colonial_universal_life_5

x

x

x

x

Colonial Life - Universal Life

colonial_universal_life_6

x

x

x

x

Colonial Life - Universal Life

colonial_universal_life_7

x

x

x

x

Colonial Life - Universal Life

colonial_universal_life_8

x

x

x

x

Colonial Life - Universal Life

colonial_universal_life_0

x

x

x

x

Colonial Life - Universal Life

colonial_universal_life_1

x

x

x

x

Colonial Life - Universal Life

colonial_universal_life_2

x

x

x

x

Colonial Life - Universal Life

colonial_universal_life_3

x

x

x

x

Colonial Life - Universal Life

colonial_universal_life_4

x

x

x

x

Colonial Life - Whole Life

colonial_whole_life_0

x

x

x

x

Colonial Life - Whole Life

colonial_whole_life_1

x

x

x

x

Colonial Life Benefits

colonial

x

x

x

x

Child Interest Sensitive Whole Life

unum_interest_sensitive_whole_life_child

x

x

x

x

Child Whole Life

unum__whole_life_child

x

x

x

x

Employee Group Critical Illness

unum_group_critical_illness_employee

x

x

x

x

Employee Group Critical Illness EE

unum_group_critical_illness_ee_employee

x

x

x

x

Employee Interest Sensitive Whole Life

unum_interest_sensitive_whole_life_employee

x

x

x

x

Employee Whole Life

unum__whole_life_employee

x

x

x

x

Group Accident

unum_group_accident_employee

x

x

x

x

Short Term Disability

unum_vwb_std_employee

x

x

x

x

Spouse Group Critical Illness

unum_group_critical_illness_spouse

x

x

x

x

Spouse Group Critical Illness EE

unum_group_critical_illness_ee_spouse

x

x

x

x

Spouse Interest Sensitive Whole Life

unum_interest_sensitive_whole_life_spouse

x

x

x

x

Spouse Whole Life

unum__whole_life_spouse

x

x

x

x

Unum Group Hospital Indemnity

unum_group_hospital_indemnity_employee

x

x

x

x

Rider Accidental Death & Dismemberment

Rider_AD&D

x

x

x

x

Rider Cancer

Rider_Cancer

x

x

x

x

Rider Child Term

Rider_Child_Term

x

x

x

x

Rider Continuation

Rider_Continuation

x

x

x

x

Rider Dental

Rider_Dental

x

x

x

x

Rider Long Term Care

Rider_Long_Term_Care

x

x

x

x

Rider Maternity

Rider_Maternity

x

x

x

x

Rider Mental Illness

Rider_Mental_Illness

x

x

x

x

Rider Pre Existing Condition

Rider_Pre_Existing_Condition

x

x

x

x

Rider Prescription

Rider_Prescription

x

x

x

x

Rider Restoration

Rider_Restoration

x

x

x

x

Rider Sports

Rider_Sports

x

x

x

x

Rider Spouse Term

Rider_Spouse_Term

x

x

x

x

Rider Subscriber Term

Rider_Subscriber_Term

x

x

x

x

Rider Terminal Illness

Rider_Terminal_Illness

x

x

x

x

Rider Terrorism

Rider_Terrorism

x

x

x

x

Rider Vision

Rider_Vision

x

x

x

x

Rider Waiver of Premium

Rider_Waiver_of_Premium

x

x

x

x