Minimum Viable Product (MVP) for HCM Data Integration

A basic HCM data integration is a one-directional push of employee demographic data from the HCM system to the PlanSource Subscriber endpoints. This guide will only cover the basic details needed for an integration. For more information about each end point, please visit the reference section.

For more information on how PlanSource treats data, performs data validation, and general best practices please review each guide in the documentation section.

When trying to access a PlanSource end point, the following 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 - Creates a new record.
PUT - Updates an existing record (Only updates fields supplied in payload request, does not replace any non-specified fields).
GET - Reads existing record.

Generating an API Token

PlanSource uses OAuth 2.0 to authenticate users/systems trying to access the PlanSource API's. Before an API call can be made, an access token must first be generated. Each access token expires after 5 minutes; best practice is to request a new access token before every API call to prevent a timeout error.

In addition to OAuth 2.0, PlanSource requires the use of Java Web Tokens (JWT). The signed token must be sent as the client_assertion along with a client_id. PlanSource will provide the following during implementation:

client_id
client_secret
logged_in_user

Please note that each client will have different values. A client's API credentials will also differ across PlanSource environments.

📘
More Information
For full details, please read the following guide on obtaining an access token.

Demographic Data

Having a data integration with PlanSource as an HCM provider involves four primary use cases.

Creating a new subscriber.
Updating an existing subscriber.
Terminating a subscriber.
Rehiring a terminated subscriber.

Please note that PlanSource refers to an employee as a subscriber. A subscriber will only refer to an employee's data. Dependents/Family Members and Beneficiaries are NOT considered subscribers.

Accessing the API's is done by applying the proper endpoint to the end of the correct API URL. For example, to create a new subscriber in the PlanSource Production environment the following would be used:

https://api.plansource.com/admin/v2/subscriber

Creating a New Subscriber

To create a new subscriber in the PlanSource Production environment, the following endpoint should be used:

https://api.plansource.com/admin/v2/subscriber

This POST endpoint is required for creating a new record. Trying to POST a new subscriber with an SSN that has already been created will result in an error. Please see the following document for a full list of demographic fields available when trying to create a new subscriber.

Please note that PlanSource does not have "hardcoded" required fields. Each field can be set as a required field by each client. This means that when submitting a payload an employee can likely be created with some of the following fields not populated or missing from the payload entirely. While the employee will get created, please note that this may affect their enrollment and cause downstream issues. As an MVP, most clients require the following fields:

Please see the following guide on List Validated Fields for more information on the fields below in additional notes.

PlanSource 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.	Do not sent with payload request. This is generated automatically and returned as a reply on a successful call.
subscriber_code	Stores a unique employee id from HCM system. Can be used in place of PlanSource subscriber id when trying to make updates to a specific subscriber. Also used as primary key for Single Sign-On (SSO). PlanSource validates the empID sent as part of SSO request against value stored in subscriber_code.	Required if HCM provider will be using a unique HCM subscriber/employee code to make updates after subscriber creation. Also required if HCM provider will be utilizing Single Sign-On to PlanSource. If using PlanSource id and not offering SSO this is not required. The option/choice to utilize PlanSource id or subscriber_code should be consistent across all clients that will be setup on the integration.
first_name	First name of subscriber
last_name	Last name of subscriber
address_1	Primary street address - must be US/Canada addresses only	Must be US/Canada addresses only
address_2	Used to store Suite #, BLDG #, etc.	Must be US/Canada addresses only
city	City - must be US/Canada addresses only	Must be US/Canada addresses only
state	State - must be US/Canada addresses only	Must be US/Canada addresses only
zip_code	Zip code	Must be US/Canada addresses only
home_phone	Home Phone/Primary Phone	Format: XXXXXXXXXX
gender	Gender of subscriber	Must be M or F
hire_date	Hire Date of subscriber - Can be future dated	Format: CCYY/MM/DD
birthdate	Birth date of subscriber	Format: CCYY/MM/DD
ssn	SSN of subscriber	Format: XXXXXXXXXXX
union_code	Union code typically is re-purposed as Department. Field used to create populations that drive benefit eligibility.	List validated field - client defined field containing a client specified list of values. Values will differ from client to client. This field is optional to clients but if client is using field, data is REQUIRED. Sending a value in this field that does not match a value configured in the list by the client will result in a validation error for that employee.
employment_level	Employment level typically stores full time (F) or part time (p) information. Field used to create populations that drive benefit eligibility.	List validated field - client defined field containing a client specified list of values. Values will differ from client to client. This field is optional to clients but if client is using field, data is REQUIRED. Sending a value in this field that does not match a value configured in the list by the client will result in a validation error for that employee.
marital_status	Marital status	Must be S, M, or U
division	Division field usually stores client divisions. Field used to create populations that drive benefit eligibility.	List validated field - client defined field containing a client specified list of values. Values will differ from client to client. This field is optional to clients but if client is using field, data is REQUIRED. Sending a value in this field that does not match a value configured in the list by the client will result in a validation error for that employee.
location	Location field usually stores client locations. Field used to create populations that drive benefit eligibility.	List validated field - client defined field containing a client specified list of values. Values will differ from client to client. This field is optional to clients but if client is using field, data is REQUIRED. Sending a value in this field that does not match a value configured in the list by the client will result in a validation error for that employee.
org_class	Class field usually stores client employee classes. Field used to create populations that drive benefit eligibility.	List validated field - client defined field containing a client specified list of values. Values will differ from client to client. This field is optional to clients but if client is using field, data is REQUIRED. Sending a value in this field that does not match a value configured in the list by the client will result in a validation error for that employee.
current_salary_effective_on	Effective Date of Salary if current_salary is sent in same payload	If current_salary is sent, this field is REQUIRED. Should be effective date of salary sent or date when API request is made.
current_salary	Stores subscriber annual salary. Used to calculate volume based benefits such as life insurance.	Required on subscriber creation
email	Email of the subscriber

📘
More Information
For full details on this endpoint, please see the reference section.

Updating a Subscriber

To update an existing single subscriber in the PlanSource Production environment, the following endpoint should be used:

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

To update multiple subscribers in a single request, the following bulk update endpoint should be used:

https://api.plansource.com/admin/v2/subscribers

Please note that the rest of this section will be written in the point of view of updating a single subscriber and not using the bulk endpoint.

This PUT endpoint will allow the specified subscriber to be updated. Trying to perform a PUT with an id that does not exist will result in an error. PlanSource does not perform an upsert and expects that the HCM system respectfully utilize the POST endpoint detailed previously for submitting new hire employees and the PUT endpoint for updating existing employees.

When sending the endpoint {id} parameter, the PlanSource id that was returned as part of the POST response is expected by default to identify which subscriber should be updated. If the HCM system is supplying a subscriber_code with the HCM system's unique employee code instead, ensure that the endpoint call includes the query parameter is_custom_id=true as this will force the API system to compare the value sent in place of id against the employee's subscriber_code instead of id.

When performing a PUT, only the fields that are being updated need to be sent in the payload. The system will not clear fields by omission. To clear a field, the field must be sent on the payload with a blank value. The PUT endpoint can be used to update nearly every field that can be sent in the POST subscriber creation endpoint.

📘
More Information
For full details on updating an existing single subscriber, please see the reference section.
For full details on updating multiple subscribers, please see the reference section.

Terminating a Subscriber

To update an existing single subscriber, the following endpoint should be used:

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

This PUT endpoint will allow the specified subscriber to be terminated. Trying to perform a PUT with an id that does not exist will result in an error.

PlanSource only supports status changes from active to terminated via API. For LOA or COBRA status, the HR administrator for the client must login to PlanSource directly and manually update the employee status to LOA or COBRA.

PlanSource Field	Description	Additional Information
termination_reason	Stores the termination reason	REQUIRED. Must be a valid termination reason PlanSource accepts. Full list of PlanSource termination reasons found in the endpoint /subscriber/meta. Termination reasons do not change and are consistent for ALL clients. Employee will be set to inactive status
termination_date	Stores the termination date	REQUIRED. Format: CCYY-MM-DD
voluntary	Stores if termination was voluntary or involuntary	OPTIONAL. Should be true or false value

📘
More Information
For full details on this endpoint, please see the reference section.

Rehiring a Subscriber

To update an existing single subscriber, the following endpoint should be used:

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

This PUT endpoint will allow the specified subscriber to be rehired. Trying to perform a PUT with an id that does not exist will result in an error.

PlanSource Field	Description	Additional Information
rehire_date	Date of the re-hire	Format: CCYY-MM-DD In PlanSource the employee's hire date field will be set with the rehire_date supplied. The employee's original_hire_date field will be set with the previous hire_date value. Employee will go from inactive to active status.

PlanSource Field

Description

Additional Information

rehire_date

Date of the re-hire

Format: CCYY-MM-DD

In PlanSource the employee's hire date field will be set with the rehire_date supplied. The employee's original_hire_date field will be set with the previous hire_date value. Employee will go from inactive to active status.

📘
More Information
For full details on this endpoint, please see the reference section.

MVP Complete

The above endpoints should be the four necessary endpoints to complete the MVP for an HCM integration. This will support a baseline of simple clients without complex implementations. Once the four use cases above have been completed and tested, the integration is considered ready for a beta client to be implemented.

For a complete HCM/Payroll Integration, please also see the following document for developing an MVP for Payroll Integration.