### GET /coverage/meta Response Example Source: https://developer.plansource.com/docs/meta-endpoints This JSON response details available termination reasons for coverage, including their unique IDs, names, and lookup codes. It is useful for understanding and populating coverage termination data. ```json { "status": "success", "errors": [], "data": { "termination_reasons": [ { "id": 1, "name": "Termination of Employment (COBRA)", "lookup_code": "employment_termination" }, { "id": 2, "name": "Termination or Employment for gross misconduct (Non-COBRA)", "lookup_code": "employment_termination_for_cause" }, ... { "id": 25, "name": "Failed to receive documentation (Non-COBRA)", "lookup_code": "failed_to_receive_documentation" } ] } } ``` -------------------------------- ### GET /subscriber/meta API Response Example Source: https://developer.plansource.com/docs/meta-endpoints This JSON object represents a typical response from the GET /subscriber/meta endpoint. It details the metadata for each subscriber field, including its updateability, whether it's required, its display caption, data type, and possible validation values. This metadata is crucial for understanding and interacting with subscriber data. ```json { "status": "success", "errors": [], "data": { "is_smoker": { "update": true, "required": false, "caption": "Tobacco User", "data_type": "STRING", "validation_data": [ [ "YES", "YES" ], [ "NO", "NO" ] ] }, "division": { "update": true, "required": false, "caption": "Division", "data_type": "STRING", "validation_data": [ [ "A", "A" ], [ "B", "B" ], [ "C", "C" ] ] }, "org_class": { "update": true, "required": false, "caption": "Class", "data_type": "STRING", "validation_data": [ [ "HOURLY", "HOURLY" ], [ "SALARY", "SALARY" ] ] }, "location": { "update": true, "required": false, "caption": "Location", "data_type": "STRING", "validation_data": [ [ "FLORIDA", "FLORIDA" ], [ "UTAH", "UTAH" ] ] }, "employment_level": { "update": true, "required": false, "caption": "Employment Level", "data_type": "STRING", "validation_data": [ [ "F", "F" ], [ "P", "P" ] ] }, "union_code": { "update": true, "required": false, "caption": "Union", "data_type": "STRING", "validation_data": [ [ "HR", "HR" ], [ "PRODUCT", "PRODUCT" ] ] }, "state": { "update": true, "required": false, "caption": "State/Province", "data_type": "STRING", "validation_data": [ [ "APO Europe", "AE" ], [ "Alabama", "AL" ] ] }, "country": { "update": true, "required": false, "caption": "Country", "data_type": "STRING" } } } ``` -------------------------------- ### GET /beneficiaries/meta Response Example Source: https://developer.plansource.com/docs/meta-endpoints This JSON response provides metadata for beneficiary fields, detailing their update status, requirement, caption, data type, and validation rules. It is used to understand the structure and constraints of beneficiary data. ```json { "status": "success", "errors": [], "data": { "relationship": { "update": true, "required": true, "caption": "Relationship", "data_type": "STRING", "validation_data": [ [ "SPOUSE", "SPOUSE" ], [ "CHILD", "CHILD" ] ] }, "allocation": { "update": true, "required": true, "caption": "Allocation", "data_type": "NUMBER", "validation_data": [ [ "25%", "25%" ], [ "50%", "50%" ], [ "100%", "100%" ] ] }, "primary_beneficiary": { "update": true, "required": true, "caption": "Primary Beneficiary", "data_type": "BOOLEAN", "validation_data": [ [ "YES", "YES" ], [ "NO", "NO" ] ] }, "termination_reason": { "update": true, "required": false, "caption": "Termination Reason", "data_type": "STRING", "validation_data": [ { "lookup_code": "death", "name": "Death (COBRA)", "description": "Death of Employee" }, { "lookup_code": "voluntary_waive", "name": "Voluntary Coverage Waive (Non-COBRA)", "description": "Subscriber voluntarily waived coverage" }, ... { "lookup_code": "other", "name": "Other (Non-COBRA)", "description": "Other" } ] } } } ``` -------------------------------- ### GET /dependent/meta JSON Response Example Source: https://developer.plansource.com/docs/meta-endpoints This JSON object represents a successful response from the GET /dependent/meta endpoint. It includes metadata for various dependent fields such as 'hide_dependent_on_termination', 'gender', 'relationship_code', 'state', 'country', 'is_smoker', and 'termination_reason'. Each field's metadata contains information like updateability, required status, a user-friendly caption, data type, and validation data specific to that field. ```json { "status": "success", "errors": [], "data": { "hide_dependent_on_termination": { "update": true, "required": false, "caption": "Hide dependent on termination", "data_type": "BOOLEAN", "validation_data": [ [ "F", "F" ], [ "P", "P" ] ] }, "gender": { "update": true, "required": true, "caption": "Gender", "data_type": "STRING", "validation_data": [ [ "Male", "M" ], [ "Female", "F" ] ] }, "relationship_code": { "update": true, "required": true, "caption": "Relationship", "data_type": "STRING", "validation_data": [ [ "Spouse", "spouse" ], [ "Child", "child" ], [ "Child Age 26 to 30", "chile_age_26_to_30" ] ] }, "state": { "update": true, "required": false, "caption": "State", "data_type": "STRING", "validation_data": [ [ "APO Europe", "AE" ], [ "Alabama", "AL" ], [ "Wyoming", "WY" ] ] }, "country": { "update": true, "required": false, "caption": "Country", "data_type": "STRING", "validation_data": [ [ "Afghanistan", "Afghanistan" ], [ "Aland Islands", "Aland Islands" ], [ "Zimbabwe", "Zimbabwe" ] ] }, "is_smoker": { "update": true, "required": false, "caption": "Tobacco User", "data_type": "STRING", "validation_data": [ [ "YES", "YES" ], [ "NO", "NO" ] ] }, "termination_reason": { "update": true, "required": false, "caption": "Termination Reason", "data_type": "NUMBER", "validation_data": [ { "lookup_code": "divorce", "name": "Divorce (COBRA)", "description": "Spouse Divorced from employee" }, { "lookup_code": "overage_child", "name": "Child becomes ineligible (COBRA)", "description": "Child ineligibile for coverage due to age" }, { "lookup_code": "dependent_death", "name": "Dependent Death (Non-COBRA)", "description": "Dependent death." } ] } } } ``` -------------------------------- ### GET /websites/developer_plansource Source: https://developer.plansource.com/docs/minimum-viable-product-mvp-for-payroll-data-integration Retrieves volume amount elected for volume based coverages and payroll record status. ```APIDOC ## GET /websites/developer_plansource ### Description This endpoint provides the elected volume amount for volume-based coverages and the status of the payroll record. ### Method GET ### Endpoint /websites/developer_plansource ### Parameters #### Query Parameters - **change_effective_date** (string) - Required - Provides the effective date of coverage for the deduction. - **current** (string) - Required - Provides status of the payroll record. Use 'Y' for the active record. #### Request Body None ### Request Example GET /websites/developer_plansource?change_effective_date=2023-01-01¤t=Y ### Response #### Success Response (200) - **volume_amount** (string) - The elected volume amount for volume based coverages. - **current** (string) - Indicates if this is the active payroll record ('Y' or 'N'). #### Response Example { "volume_amount": "1000.00", "current": "Y" } ``` -------------------------------- ### Get Developer Plan Details Source: https://developer.plansource.com/docs/table-of-coverage-fields Retrieves detailed information about a specific developer plan, including its structure, coverage, and associated policies. ```APIDOC ## GET /websites/developer_plansource/{coverage_id} ### Description Retrieves detailed information about a specific developer plan using its coverage ID. ### Method GET ### Endpoint `/websites/developer_plansource/{coverage_id}` ### Parameters #### Path Parameters - **coverage_id** (integer) - Required - The unique identifier for the coverage. #### Query Parameters - **start_date** (string) - Optional - The start date for filtering plan data. - **end_date** (string) - Optional - The end date for filtering plan data. - **page** (string) - Optional - The page number for pagination. - **per_page** (string) - Optional - The number of items per page for pagination. - **Include_test** (string) - Optional - Whether to include test employees in the results. ### Response #### Success Response (200) - **gi_coverage_level_id** (integer) - GI Coverage Level ID - **gi_dependent_ids** (array) - GI Dependent IDS - **gi_subscriber_election_amount** (number) - GI Subscriber Election Amount - **esigned_at** (string) - E-signed At - **esigned_by** (string) - E-signed By - **waive_plan_policyholder** (string) - Waive Plan Policyholder - **waive_plan_insurer** (string) - Waive Plan Insurer - **waive_plan_insurer_phone** (string) - Waive Plan Insurer Phone - **waive_plan_effective_date** (string) - Waive Plan Effective Date - **waive_plan_termination_date** (string) - Waive Plan Termination Date - **beneficiary_esign_at** (string) - Beneficiary E-sign At - **beneficiary_esign_by** (string) - Beneficiary E-sign By - **subscriber_ytd** (number) - Subscriber Year to Date - **org_ytd** (number) - Org Year to Date - **subscriber_ytd_effective_date** (string) - Subscriber Year to Date Effective Date - **org_ytd_effective_date** (string) - Org Year to Date Effective Date - **deny_pend_permanently_amount** (number) - Deny Pend Permanently Amount - **waiting_for_doc_requests** (string) - Waiting for Doc Requests - **hsa_contribution_end_date** (string) - HSA Contribution End Date - **req_hsa_contribution_end_date** (string) - Requested HSA Contribution End Date - **bookkeeping_values** (object) - Bookkeeping Values - **plan_structure** (object) - Plan Structure - **name** (string) - Name - **lookup_code** (string) - Lookup Code - **coverage_id** (integer) - Coverage ID - **policy** (string) - Policy - **pretax** (string) - Pretax - **coverage_line_id** (integer) - Coverage Line ID - **dependent_coverage_id** (integer) - Dependent Coverage ID - **dependent_id** (integer) - Unique ID for Dependent #### Response Example ```json { "gi_coverage_level_id": 1, "gi_dependent_ids": [101, 102], "gi_subscriber_election_amount": 500.00, "esigned_at": "2023-01-15T10:00:00Z", "esigned_by": "John Doe", "waive_plan_policyholder": "Yes", "waive_plan_insurer": "Example Insurance", "waive_plan_insurer_phone": "123-456-7890", "waive_plan_effective_date": "2023-01-01", "waive_plan_termination_date": "2023-12-31", "beneficiary_esign_at": "2023-01-15T10:05:00Z", "beneficiary_esign_by": "Jane Smith", "subscriber_ytd": 1200.00, "org_ytd": 1500.00, "subscriber_ytd_effective_date": "2023-01-01", "org_ytd_effective_date": "2023-01-01", "deny_pend_permanently_amount": 0.00, "waiting_for_doc_requests": "No", "hsa_contribution_end_date": "2023-12-31", "req_hsa_contribution_end_date": "2023-11-30", "bookkeeping_values": { "key": "value" }, "plan_structure": { "name": "Gold Plan", "lookup_code": "GP123", "coverage_id": 1, "policy": "P-XYZ", "pretax": "Yes", "coverage_line_id": 10 }, "dependent_coverage_id": 201, "dependent_id": 101 } ``` ``` -------------------------------- ### Get Subscribers API Source: https://developer.plansource.com/docs/utilize-postman Retrieves a list of all subscribers and their stored demographic data. ```APIDOC ## GET Subscribers ### Description Retrieves a list of all subscribers along with their demographic data. This endpoint is useful for fetching multiple subscriber records at once. ### Method GET ### Endpoint /Demographic/Get Subscribers ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) - **subscribers** (array) - A list of subscriber objects, each containing demographic data. #### Response Example ```json { "subscribers": [ { "id": "subscriber-abc-123", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" }, { "id": "subscriber-def-456", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ] } ``` ``` -------------------------------- ### JSON Employee Groups API Response Example Source: https://developer.plansource.com/docs/guide-on-list-validated-fields This JSON excerpt shows a sample response from the GET /subscriber/meta endpoint after managing list validated fields in Employee Groups. It details fields like 'org_class' and 'location', including their update status, requirement, caption, data type, and the validation data (list of valid values). ```json "org_class": { "update": true, "required": false, "caption": "Class", "data_type": "STRING", "validation_data": [ [ "HOURLY", "HOURLY" ], [ "SALARY", "SALARY" ] ] }, "location": { "update": true, "required": false, "caption": "Location", "data_type": "STRING", "validation_data": [ [ "FLORIDA", "FLORIDA" ], [ "UTAH", "UTAH" ] ] } ``` -------------------------------- ### GET /payroll_coverages_subscriber/{id} or /payroll_coverages_subscribers Source: https://developer.plansource.com/docs/sop-on-payroll-business-rules Retrieve payroll coverages for a subscriber or a list of subscribers within a specified date range. The `start_date` and `end_date` query parameters are required for these calls. ```APIDOC ## GET /payroll_coverages_subscribers ### Description Retrieves a list of payroll coverages for subscribers within a specified date range. ### Method GET ### Endpoint `/payroll_coverages_subscribers` ### Query Parameters - **start_date** (string) - Required - The start date for the payroll coverage range (e.g., 'MM-DD-YYYY'). - **end_date** (string) - Required - The end date for the payroll coverage range (e.g., 'MM-DD-YYYY'). ### Request Example ```curl curl --request GET \ --url 'https://example.com/admin/payroll_coverages_subscribers?start_date=01-04-2018&end_date=01-03-2019' ``` ### Response #### Success Response (200) - **subscriber_data** (object) - Contains subscriber coverage information. - **coverage_details** (array) - Details of the subscriber's coverage. #### Response Example ```json { "subscriber_data": { "subscriber_id": "12345", "coverage_details": [ { "plan_name": "Medical Plan", "coverage_start": "01-01-2018", "coverage_end": "12-31-2018" } ] } } ``` ``` -------------------------------- ### Post Subscriber API Source: https://developer.plansource.com/docs/utilize-postman Creates a new subscriber by sending their information to the API. Subscriber data can be derived from a 'GET Subscriber Meta' call. ```APIDOC ## POST Subscriber ### Description Creates a new subscriber by submitting their demographic information. The subscriber's information can be sourced from the 'GET Subscriber Meta' endpoint. ### Method POST ### Endpoint /Demographic/Post Subscriber ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **subscriber_info** (object) - Required - An object containing all the subscriber's information. - **first_name** (string) - Required - The subscriber's first name. - **last_name** (string) - Required - The subscriber's last name. - **email** (string) - Required - The subscriber's email address. - **employee_id** (string) - Optional - The subscriber's employee ID. - **payroll_schedule_id** (string) - Optional - The ID of the subscriber's payroll schedule. ### Request Example ```json { "subscriber_info": { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "employee_id": "E12345", "payroll_schedule_id": "12345" } } ``` ### Response #### Success Response (200) - **created_subscriber** (object) - The information of the newly created subscriber. #### Response Example ```json { "created_subscriber": { "id": "subscriber-abc-123", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "employee_id": "E12345", "payroll_schedule_id": "12345" } } ``` ``` -------------------------------- ### GET /websites/developer_plansource/payroll Source: https://developer.plansource.com/docs/table-of-payroll-fields Retrieves payroll data. The 'id', 'start_date', and 'end_date' fields can be used as parameters in the endpoint URL to filter results. Developers are not required to fill out every data field, but some are mandatory for successful retrieval. ```APIDOC ## GET /websites/developer_plansource/payroll ### Description Retrieves payroll data. The 'id', 'start_date', and 'end_date' fields can be used as parameters in the endpoint URL to filter results. Developers are not required to fill out every data field, but some are mandatory for successful retrieval. ### Method GET ### Endpoint /websites/developer_plansource/payroll ### Parameters #### Query Parameters - **id** (integer) - Optional - Unique ID for subscriber. Used as a parameter in endpoint URL. - **start_date** (date) - Optional - Start Date. Used as a parameter in endpoint URL. - **end_date** (date) - Optional - End Date. Used as a parameter in endpoint URL. #### Request Body None ### Response #### Success Response (200) - **id** (integer) - Unique ID for subscriber. - **start_date** (date) - Start Date. - **end_date** (date) - End Date. - **first_name** (string) - First Name. - **last_name** (string) - Last Name. - **middle_name** (string) - Middle Name. - **ssn** (string) - SSN. - **pay_frequency** (integer) - Pay Frequency. - **plan_year_starts_on** (string) - Plan Year Starts On. - **plan_year_ends_on** (string) - Plan Year Ends On. - **benefit_name** (string) - Benefit Name. - **benefit_lookup_code** (string) - Benefit Lookup Code. - **plan_name** (string) - Plan Name. - **coverage_level** (string) - Coverage Level. - **subscriber_premium** (number) - Subscriber Premium. - **org_premium** (number) - Org Premium. - **imputed_income** (number) - Imputed Income. - **subscriber_pretax_premium** (number) - Subscriber Pretax Premium. - **subscriber_posttax_premium** (number) - Subscriber Posttax Premium. - **tax_treatment** (string) - Tax Treatment. - **volume** (number) - Volume. - **subscriber_fsa_amount** (number) - Subscriber FSA Amount. - **org_fsa_amount** (number) - Org FSA Amount. - **original_effective_date** (string) - Original Effective Date. - **change_effective_date** (string) - Change Effective Date. #### Response Example ```json { "id": 12345, "start_date": "2023-01-01", "end_date": "2023-12-31", "first_name": "John", "last_name": "Doe", "middle_name": "A", "ssn": "***-**-1234", "pay_frequency": 2, "plan_year_starts_on": "2023-01-01", "plan_year_ends_on": "2023-12-31", "benefit_name": "Medical", "benefit_lookup_code": "MED001", "plan_name": "Gold Plan", "coverage_level": "Employee Only", "subscriber_premium": 100.50, "org_premium": 200.75, "imputed_income": 5.25, "subscriber_pretax_premium": 75.00, "subscriber_posttax_premium": 25.50, "tax_treatment": "Pre-Tax", "volume": 1, "subscriber_fsa_amount": 0, "org_fsa_amount": 0, "original_effective_date": "2023-01-01", "change_effective_date": "2023-01-01" } ``` ``` -------------------------------- ### Retrieve Payroll Coverages with Date Range using cURL Source: https://developer.plansource.com/docs/sop-on-payroll-business-rules This snippet demonstrates how to retrieve payroll coverage data for a specific date range using a cURL GET request. It requires both 'start_date' and 'end_date' parameters in the URL. This is primarily used for accessing payroll changes for subscribers. ```cURL curl --request GET \ --url 'https://example.com/admin/payroll_coverages_subscribers?start_date=01-04-2018&end_date=01-03-2019' ``` -------------------------------- ### Example GET /subscriber/meta Response for Data Field Captions Source: https://developer.plansource.com/docs/guide-on-list-validated-fields This JSON snippet shows an excerpt from the GET /subscriber/meta endpoint response after managing list validated fields. It illustrates how 'pay_rate' is configured as a list validated field with specific values. ```json { "pay_rate": { "update": true, "required": false, "caption": "Pay Rate", "data_type": "NUMBER", "validation_data": [ [ "20", "20" ], [ "40", "40" ], [ "80", "80" ] ] } } ``` -------------------------------- ### Accessing the Resource Server Source: https://developer.plansource.com/docs/obtaining-an-access-token-to-admin-api Instructions on how to use the obtained access token to make authenticated requests to the Resource Server. ```APIDOC ## Accessing the Resource Server ### Description Use the obtained access token to make authenticated requests to the Resource Server by including it as a Bearer token in the `Authorization` header. ### Method Any (e.g., GET, POST, PUT, DELETE) ### Endpoint [Resource Server Endpoint] ### Parameters #### Path Parameters None specific to token usage. #### Query Parameters None #### Request Body None specific to token usage. ### Request Example ``` GET /api/resource HTTP/1.1 Host: resource-server.example.com Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA ``` ### Response #### Success Response (200) - **[Resource Specific Fields]** - Description of the successful response data. #### Response Example ```json { "data": "..." } ``` ### Note Only the `Authorization: Bearer ` header method is supported for passing the Bearer token. Form-Encoded Body Parameters and URI Query Parameters are not supported for security reasons. ``` -------------------------------- ### PlanSource SAML SSO Configuration Source: https://developer.plansource.com/docs/plansourceokta-saml-sso This section details the configuration parameters required in Okta to establish a SAML SSO connection with PlanSource. ```APIDOC ## PlanSource SAML SSO Configuration ### Description Details the necessary settings within Okta for configuring a SAML SSO connection to PlanSource. This includes connection URLs, entity IDs, attribute mappings, and advanced security settings. ### Method N/A (Configuration Guide) ### Endpoint N/A (Configuration Guide) ### Parameters #### Connection Information - **Single Sign On URL** (URL) - Required - The assertion consumer service (ACS) URL for PlanSource. - **Audience URI (SP Entity ID)** (URL) - Required - The unique identifier for PlanSource as the service provider. - **Default Relay State** (String) - Required - Client-specific value provided by PlanSource. - **Name ID Format** (String) - Required - The format for the Name ID element in SAML assertions (Unspecified). - **Application Username** (String) - Required - The attribute in Okta to be used as the username for SAML (Okta username). #### Advanced Settings - **Response** (String) - Required - Whether the SAML response should be signed (Signed). - **Assertion Signature** (String) - Required - Whether the SAML assertion should be signed (Signed). - **Signature Algorithm** (String) - Required - The algorithm used for signing (RSA-SHA256). - **Digest Algorithm** (String) - Required - The algorithm used for digest (SHA256). - **Assertion Encryption** (String) - Required - Whether SAML assertions should be encrypted (Unencrypted). - **Enable Single Logout** (Boolean) - Optional - Whether to enable SAML single logout (Optional). - **Authentication Context Class** (String) - Required - The authentication context class reference (PasswordProtectedTransport). - **Honor Force Authentication** (String) - Required - Whether to honor the Force Authentication flag (Yes). - **SAML Issuer ID** (URL) - Required - The entity ID for Okta (http://www.okta.com/\${org.externalKey}). #### Attribute Statements - **empID** (String) - Required - Maps to the user's email address (user.email). ### Request Example N/A ### Response N/A ### Error Handling Consult your Okta Representative and PlanSource account manager for specific error resolution. ``` -------------------------------- ### Retrieving Payroll Schedule ID via API Source: https://developer.plansource.com/docs/sop-on-payroll-business-rules PlanSource assigns unique IDs to payroll schedules. Developers must retrieve these IDs using a GET call to the /subscriber/meta endpoint, as these IDs are required for assigning payroll schedules to subscribers via API calls. The excerpt shows an example response containing the ID, name, and lookup code for a payroll schedule. ```json "payroll_schedules": [ { "id": 563, "name": "Biweekly (26 per year)", "lookup_code": "biweekly26_1" } ``` -------------------------------- ### Rehire Subscriber using PlanSource API (cURL) Source: https://developer.plansource.com/docs/demo-use-cases Example of rehiring a terminated subscriber using the PUT /subscriber/{id}/rehire endpoint via cURL. Requires the subscriber ID and the rehire date. This is a direct API call example. ```curl curl --request PUT \ --url https://example.com/admin/subscriber/87459963/rehire \ --data '{"rehire_date":"04/14/2018"}' ``` -------------------------------- ### Creating a New Subscriber Source: https://developer.plansource.com/docs/minimum-viable-product-for-hcm-data-integration This endpoint allows for the creation of new subscriber records in the PlanSource Production environment. It's a POST request that requires specific demographic fields, with some fields being conditionally required based on client configuration and integration needs like SSO. ```APIDOC ## POST /admin/v2/subscriber ### Description Creates a new subscriber record in the PlanSource Production environment. Duplicate SSNs will result in an error. Refer to the [subscriber fields documentation](https://dash.readme.io/project/plansource-dev/v2.0/docs/table-of-subscriber-fields) for a complete list of available fields. ### Method POST ### Endpoint https://api.plansource.com/admin/v2/subscriber ### Parameters #### Request Body - **subscriber_code** (string) - Required/Optional - Stores a unique employee ID from the HCM system. Required if using HCM system codes for updates or for Single Sign-On (SSO). - **first_name** (string) - Required/Optional - First name of the subscriber. - **last_name** (string) - Required/Optional - Last name of the subscriber. - **address_1** (string) - Required/Optional - Primary street address (US/Canada only). - **address_2** (string) - string - Used to store Suite #, BLDG #, etc. (US/Canada only). - **city** (string) - Required/Optional - City name (US/Canada only). - **state** (string) - Required/Optional - State name (US/Canada only). - **zip_code** (string) - Required/Optional - Zip code (US/Canada only). - **home_phone** (string) - Required/Optional - Home phone number. Format: XXXXXXXXXX. - **gender** (string) - Required/Optional - Gender of the subscriber. Must be 'M' or 'F'. - **hire_date** (string) - Required/Optional - Hire date of the subscriber. Format: CCYY/MM/DD. - **birthdate** (string) - Required/Optional - Birth date of the subscriber. Format: CCYY/MM/DD. - **ssn** (string) - Required/Optional - Social Security Number of the subscriber. Format: XXXXXXXXXXX. ### Request Example ```json { "subscriber_code": "EMP12345", "first_name": "John", "last_name": "Doe", "address_1": "123 Main St", "city": "Anytown", "state": "CA", "zip_code": "90210", "home_phone": "5551234567", "gender": "M", "hire_date": "2023/01/15", "birthdate": "1990/05/20", "ssn": "12345678901" } ``` ### Response #### Success Response (200) - **id** (string) - PlanSource subscriber ID, unique to each subscriber. Returned automatically after a successful call. #### Response Example ```json { "id": "ps_subscriber_98765" } ``` ``` -------------------------------- ### Employee Demographic Data Example (JSON) Source: https://developer.plansource.com/docs/employee-payroll-deduction-life-cycle This JSON object represents the demographic data for an employee, including personal information, employment details, and benefit-related fields. It serves as an example of the data structure that might be exchanged or stored within the PlanSource system for employee payroll deductions. ```json { "status": "success", "errors": [], "data": { "links": [ { "href": "/admin/subscriber/Payroll_1?is_custom_id=true", "rel": "self" } ], "id": 19147266, "subscriber_code": "Payroll_1", "first_name": "Payroll", "last_name": "Test1", "middle_name": "E", "address_1": "123 Main Street", "address_2": "Apartment 54", "city": "Jacksonville", "state": "FL", "zip_code": "32777", "country": "United States", "home_phone": "4075553333", "work_phone": "4075552222", "cell_phone": "4075551111", "gender": "M", "hire_date": "2018/07/10", "birthdate": "1984/02/22", "ssn": "555724484", "termination_date": null, "union_code": "LOCAL56", "employment_level": "FT", "pay_rate": "10.0", "pay_type": null, "org_payroll_id": 111106, "employee_number": "135538", "public_id": 997306, "marital_status": "U", "division": "A", "location": "FLORIDA", "org_class": "SALARIED", "business_title": "Org Tester", "udef_1": null, "udef_2": null, "udef_3": null, "udef_4": null, "udef_5": null, "udef_6": null, "udef_7": null, "udef_8": null, "udef_9": null, "udef_10": null, "udef_11": null, "udef_12": null, "udef_13": null, "udef_14": null, "udef_15": null, "udef_16": null, "udef_17": null, "udef_18": null, "udef_19": null, "udef_20": null, "ee_code": null, "benefit_company": null, "original_hire_date": "2018/07/10", "seniority_date": null, "employment_status": null, "employment_status_starts_on": null, "employee_type": null, "current_salary_effective_on": "2018/03/10", "current_salary": "450500.0", "benefit_deduction_group": null, "highly_compensated": null, "vip": null, "fmla": null, "name_suffix": null, "benefits_start_date": "2018/07/10", "test_employee": false, "is_voluntary_termination": false, "hide_from_payroll": false, "termination_reason_id": null, "shareholder": false, "owner": false, "hours_per_week": 40, "is_smoker": null, "county": null, "udef_21": null, "udef_22": null, "udef_23": null, "udef_24": null, "udef_25": null, "udef_26": null, "udef_27": null, "udef_28": null, "udef_29": null, "udef_30": null, "email": "post@apiuser.com", "user_name": "INTEGRATIONTEST_1", "email2": "", "preferred_locale": null } } ``` -------------------------------- ### Process EOI - Approve All Action (JSON) Source: https://developer.plansource.com/docs/eoi-approval-processing This snippet demonstrates how to make a PUT call to the EOI API to process a subscriber's pending Employee Open Enrollment (EOI) with the 'approve_all' action. It includes the required URL structure, the request body with parameters like 'ssn', 'benefit_lookup_code', 'action', 'approved_amount', and 'effective_date', and the expected JSON response indicating a successful processing. ```json PUT https://partner-dev-api.plansource.com/v2/eoi/decision/2852117 BODY: { "decisions": [ { "ssn": "123000000", "benefit_lookup_code": "subscriber_life", "action": "approve_all", "approved_amount": 150000, "effective_date": "2017-03-31", "original_effective_date": "" } ] } RESPONSE: { "status": "success", "data": { "valid_count": 1, "failed_count": 0, "failed_rows": [] } } ``` -------------------------------- ### Payroll Fields Documentation Source: https://developer.plansource.com/docs/minimum-viable-product-mvp-for-payroll-data-integration This section details the various fields used in payroll integrations with PlanSource. It covers field names, descriptions, and specific usage notes. ```APIDOC ## Payroll Fields API Documentation ### Description This API endpoint provides information about the fields used for payroll integrations. It details each field's purpose, how it's used in requests and responses, and any specific requirements or optional parameters associated with it. ### Method GET ### Endpoint /websites/developer_plansource/payroll_fields ### Parameters #### Query Parameters - **id** (string) - Required - PlanSource subscriber ID. Used when making updates to a specific subscriber. - **subscriber_code** (string) - Optional - HCM/Payroll system unique employee ID. Can be used in place of PlanSource subscriber ID. - **is_custom_id** (boolean) - Optional - If true, use `subscriber_code` for requests. - **start_date** (string) - Optional - Filter data by start date (Format: CCYY/MM/DD). - **end_date** (string) - Optional - Filter data by end date (Format: CCYY/MM/DD). #### Request Body This endpoint does not typically require a request body for GET requests. Data is usually passed via query parameters or path parameters. ### Request Example ```json { "description": "Example GET request to retrieve payroll fields for a specific subscriber.", "request": "GET /websites/developer_plansource/payroll_fields?id=12345&start_date=2023/01/01" } ``` ### Response #### Success Response (200) - **id** (string) - PlanSource subscriber ID. - **subscriber_code** (string) - HCM/Payroll system unique employee ID. - **start_date** (string) - The start date associated with the payroll data. - **end_date** (string) - The end date associated with the payroll data. - **is_custom_id** (boolean) - Indicates if a custom ID was used. - **org_plan_year_starts** (string) - The start date of the benefit plan year (Format: CCYY/MM/DD). - **org_plan_year_ends** (string) - The end date of the benefit plan year (Format: CCYY/MM/DD). - **benefit_lookup_code** (string) - The deduction code for the current benefit (Required). - **plan_name** (string) - The name of the elected plan (Optional). - **coverage_level** (string) - The coverage level elected by the subscriber (Optional). - **subscriber_premium** (string) - Per-pay-period deduction amount for the employee (Required). - **org_premium** (string) - Per-pay-period earnings amount for the employer (Optional). - **imputed_income** (string) - Per-pay-period earnings amount for imputed income (Optional). - **subscriber_pretax_premium** (string) - Per-pay-period breakdown of pretax premium (Optional). - **subscriber_posttax_premium** (string) - Per-pay-period breakdown of posttax premium (Optional). - **tax_treatment** (string) - Tax treatment of the premium ('pretax' or 'posttax') (Required). - **volume** (string) - The volume associated with the payroll data. #### Response Example ```json { "description": "Example successful response containing payroll field data.", "response": { "id": "subscriber_123", "subscriber_code": "emp_456", "start_date": "2023/01/01", "end_date": "2023/12/31", "is_custom_id": false, "org_plan_year_starts": "2023/01/01", "org_plan_year_ends": "2023/12/31", "benefit_lookup_code": "HEALTH01", "plan_name": "Gold Health Plan", "coverage_level": "Employee Only", "subscriber_premium": "50.00", "org_premium": "100.00", "imputed_income": "5.00", "subscriber_pretax_premium": "30.00", "subscriber_posttax_premium": "20.00", "tax_treatment": "pretax", "volume": "1" } } ``` ### Further Information For a comprehensive list of payroll fields, please refer to the official documentation: [https://developer.plansource.com/v2.0/docs/table-of-payroll-fields](https://developer.plansource.com/v2.0/docs/table-of-payroll-fields) ``` -------------------------------- ### Get Single Subscriber API Source: https://developer.plansource.com/docs/utilize-postman Retrieves demographic data for a specific subscriber using their ID. ```APIDOC ## GET Subscriber ID ### Description Retrieves all demographic data for a single subscriber. This is useful when the 'Get Subscribers' endpoint returns too many results, and you need information for a specific individual. ### Method GET ### Endpoint /admin/v2/subscriber/{{id}} ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the subscriber. #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) - **subscriber_data** (object) - Contains all demographic data for the specified subscriber. #### Response Example ```json { "subscriber_data": { "id": "subscriber-abc-123", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "employee_id": "E12345", "payroll_schedule_id": "12345" } } ``` ``` -------------------------------- ### Developer Plan Source Fields Source: https://developer.plansource.com/docs/table-of-subscriber-fields This section details the fields available for the developer plan source, including their data types and descriptions. ```APIDOC ## Developer Plan Source Fields ### Description This endpoint provides details about the fields associated with a developer plan source. ### Method GET ### Endpoint /websites/developer_plansource ### Parameters #### Query Parameters - **fields** (string) - Optional - Comma-separated list of fields to retrieve. ### Request Body None ### Response #### Success Response (200) - **udef_10** (string) - User Defined Field 10 - **termination_reasons** (string) - Termination Reasons - **relationships** (string) - Relationships - **name** (string) - Name - **lookup_code** (string) - Lookup Code - **id** (integer) - ID - **subscriber_id** (string) - Subscriber ID #### Response Example ```json { "udef_10": "Example UDEF 10", "termination_reasons": "Example Termination Reasons", "relationships": "Example Relationships", "name": "Example Name", "lookup_code": "EXAMPLE_LC", "id": 123, "subscriber_id": "SUB123" } ``` ```