Minimum Viable Product (MVP) for HCM Data Integration
The following instructions are what is considered necessary to facilitate a HCM specific data integration between an HCM system and the PlanSource standard Admin API's.
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 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. |
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.
Updated almost 5 years ago