Minimum Viable Product (MVP) for Payroll Data Integration

A basic payroll data integration is a one-directional pull of employee deduction data from the PlanSource payroll deduction endpoints to the payroll vendor system. This guide will only cover the basic details needed for an integration. For more information about all of the PlanSource API endpoints, please visit the reference section here:

https://developer.plansource.com/reference

For more information as to how PlanSource treats data, performs data validation, and general best practices please review each guide in the documentation section here:

https://developer.plansource.com/docs

When trying to access a PlanSource endpoint, the follow URL's should be used:

PlanSource Production Environment: https://api.plansource.com/admin/v2/
PlanSource Parnter-Dev Environment: https://partner-dev-api.plansource.com/admin/v2/

The production environment is used for sending data to the live client, while all integration testing should be done against the Partner-Dev environment unless otherwise stated.

PlanSource also uses a RESTful API with the following concepts:

POST - Create a new record
PUT - Update an existing record (Only updates fields supplied in payload request, does not replace any non-specified fields)
GET - Read existing record

Payroll Deduction Data

When trying to access payroll deduction data out of PlanSource the recommended method is to get records via a single request for each employee using the following endpoint:

https://api.plansource.com/admin/v2//payroll_coverages_subscriber/{id}

The reference guide for this endpoint can be found here: https://developer.plansource.com/v2.0/reference#get_payroll-coverages-subscriber-id

PlanSource does offer a bulk payroll deduction pull for all subscribers however we do not recommend this due to the number of records that can be returned for any client larger than 200 employees.

When performing a GET request against the individual payroll deduction endpoint, the request requires an employee {id} value which can either be the PlanSource subscriber id or a custom id. The custom id needs to be tied to each employee prior to being able to make a request out of the system using that id. To use the custom id, please include the query parameter is_custom_id=true.

Payroll Fields

The table below will cover the fields typically used. For a full list please see the following page: https://developer.plansource.com/v2.0/docs/table-of-payroll-fields

Payroll Field	Description	Additional Notes
id	PlanSource subscriber id. This id is unique to all subscribers in PlanSource. Returned as part a response after a successful call. Used when making updates to a specific subscriber.	(Endpoint path parameter) Returned in response on a successful call.
subscriber_code	HCM/Payroll system unique employee id. Can be used in place of PlanSource subscriber id when requesting data.	(Endpoint path parameter) As part of payroll request, use query parameter is_custom_id=true to supply the payroll system employee id in place of PlanSource subscriber id. Returned in response on a successful call.
start_date		(Query parameter)
end_date		(Query parameter)
is_custom_id		(Query parameter)
org_plan_year_starts	Format: CCYY/MM/DD Provides start date of benefit plan year	(Optional)
org_plan_year_ends	Format: CCYY/MM/DD Provides end date of benefit plan year	(Optional) Can be used to set a deduction end date when deduction is first obtained.
benefit_lookup_code	Provides the deduction code for current benefit.	(Required) As of today, PlanSource provides a standard static non-customized deduction code for determining which benefit a deduction is tied to.
plan_name	Provides the actual name of the plan elected by the subscriber	(Optional) Only needed if payroll system will show actual plan name elected.
coverage_level	Provides the coverage level elected by the subscriber	(Optional) Only needed if payroll system will show coverage tier level.
subscriber_premium	Provides per-pay-period deduction amount for employee	(Required)
org_premium	Provides per-pay-period earnings amount for employer	(Optional) Only needed if client in payroll system will need to display employer paid amounts.
imputed_income	Provides per-pay-period earnings amount for imputed income	(Optional) Only needed if client in payroll system will need to display imputed_income amounts.
subscriber_pretax_premium	Provides per-pay-period breakdown of pretax side of subscriber_premium when imputed income calculations are used	Not part of MVP. Should be supported after MVP for maximum client adoption rate on integration.
subscriber_posttax_premium	Provides per-pay-period breakdown of posttax side of subscriber_premium when imputed income calculations are used	Not part of MVP. Should be supported after MVP for maximum client adoption rate on integration.
tax_treatment	pretax or posttax values	(Required) Used in determining if plan elected by employee is pretax vs posttax. Should be used with benefit_lookup_code to help assign subscriber_premium amount to correct deduction code in payroll system.
volume	Provides elected volume amount of volume based coverages.	(Optional) Only needed if client in payroll system will need to display volume amount elected for benefits such as life and other volume based benefits.
change_effective_date	Provides the effective date of coverage for the deduction	(Required) Used to set the effective date of coverage for a deduction.
current	Provides status of the payroll record	(Required) PlanSource provides historical payroll data. The current field is necessary to determine what the current deduction record is. If current=Y this is the active record
updated_at	Provides actual date/time deduction was updated at	(Not Needed) Date used in determining if deduction is within the start_date/end_date period supplied as part of request.
termination_date
termination_reason