Employment Changes

Benbase provides API endpoints to handle employment lifecycle events including new hires, terminations, demographic updates and compensation changes.

New Hire

This endpoint should be called whenever a new employee is added to an existing employer.

POST /employee-changes/new-hire

Request Payload

{
  "employer_id": "emp_123456789",
  "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
  "first_name": "John",
  "last_name": "Doe",
  "dob": "1990-01-15",
  "address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip_code": "10001"
  },
  "hire_date": "2024-01-15",
  "ssn": "123-45-6789",
  "email": "john.doe@example.com",
  "phone_number": "5551234567",
  "biological_sex": "male",
  "hours_worked": "40",
  "pay_frequency": "biweekly",
  "pay_rate": [
    {
      "amount": "25.50",
      "period": "hourly",
      "effective_start": "2024-01-15"
    }
  ],
  "employment_status": "full_time",
  "job_title": "Software Engineer"
}

Required Fields

Field	Type	Description	Validation
`employer_id`	string	Unique identifier for the employer	Required, min 1 character
`employee_id`	string	Unique identifier for the employee	Required, min 1 character
`first_name`	string	Employee's first name	Required, max 255 characters
`last_name`	string	Employee's last name	Required, max 255 characters
`dob`	string	Date of birth	Required, YYYY-MM-DD format
`employer`	string	Employer name	Required, min 1 character
`address`	object	Employee's address	Required, see Address fields below
`hire_date`	string	Employee's hire date	Required, YYYY-MM-DD format
`email`	string	Employee's email address	Required, valid email format, max 254 characters
`hours_worked`	string	Hours worked per week	Required
`pay_rate`	array	Employee's pay rate information	Required, array of pay rate objects
`employment_status`	string	Employment status	Required, `full_time` or `part_time`

If you have a personal email address, use that one as benefits could continue after unemployment. If not, use work email instead.

Optional Fields

Field	Type	Description	Validation
`ssn`	string	Social Security Number	Optional
`phone_number`	string	Employee's phone number	Optional, max 10 characters
`termination_date`	string	Employee's termination date	Optional, YYYY-MM-DD format
`biological_sex`	string	Employee's biological sex	Optional, `male` or `female`
`pay_frequency`	string	Pay frequency	Optional, `weekly`, `biweekly`, `semimonthly`, or `monthly`
`job_title`	string	Employee's job title	Optional, max 255 characters

Address Fields

Field	Type	Required	Description
`line1`	string	Yes	Primary address line
`line2`	string	No	Secondary address line (apartment, suite, etc.)
`city`	string	Yes	City name
`state`	string	Yes	State code: `AL` `AK` `AZ` `AR` `CA` `CO` `CT` `DE` `DC` `FL` `GA` `HI` `ID` `IL` `IN` `IA` `KS` `KY` `LA` `ME` `MD` `MA` `MI` `MN` `MS` `MO` `MT` `NE` `NV` `NH` `NJ` `NM` `NY` `NC` `ND` `OH` `OK` `OR` `PA` `RI` `SC` `SD` `TN` `TX` `UT` `VT` `VA` `WA` `WV` `WI` `WY`
`zip_code`	string	Yes	ZIP code

Pay Rate Fields

Field	Type	Required	Description	Validation
`amount`	string	Yes	Pay rate amount	Required, must be 0 or more, rounded to 2 decimal places (e.g., 2.55)
`period`	string	Yes	Pay rate period	Required, see Period options below
`effective_start`	string	Yes	When the pay rate becomes effective	Required, YYYY-MM-DD format

Period Options

Period	Description
`hourly`	Hourly rate
`annually`	Annual rate

Sample Code

curl -X POST {{API_BASE_URL}}/employee-changes/new-hire \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_id": "emp_123456789",
    "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
    "first_name": "John",
    "last_name": "Doe",
    "dob": "1990-01-15",
    "address": {
      "line1": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "zip_code": "10001"
    },
    "hire_date": "2024-01-15",
    "email": "john.doe@example.com",
    "hours_worked": "40",
    "pay_frequency": "biweekly",
    "pay_rate": [
      {
        "amount": "25.50",
        "period": "hourly",
        "effective_start": "2024-01-15"
      }
    ],
    "employment_status": "full_time"
  }'

Termination

Should be used to notify when an existing employee is going to be terminated. All post-termination processes are handled automatically by Benbase.

POST /employee-changes/termination

Request Payload

{
  "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
  "termination_date": "2024-12-31"
}

Fields

Field	Type	Required	Description	Validation
`employee_id`	string	Yes	Employee ID	Required, min 1 character
`termination_date`	string	Yes	Employee's termination date	Required, YYYY-MM-DD format

All processes that follow after termination are handled by Benbase automatically

Sample Code

curl -X POST {{API_BASE_URL}}/employee-changes/termination \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
    "termination_date": "2024-12-31"
  }'

Demographic Update

Update an existing employee's address information. This endpoint is used when an employee moves to a different address or state.

POST /employee-changes/demographic

Request Payload

{
  "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
  "address": {
    "line1": "456 New Street",
    "line2": "Unit 7C",
    "city": "Los Angeles",
    "state": "CA",
    "zip_code": "90210"
  }
}

Fields

Field	Type	Required	Description	Validation
`employee_id`	string	Yes	Employee ID	Required, min 1 character
`address`	object	Yes	Updated address information	Required, see Address fields above

This endpoint is specifically for address changes and state relocations

Sample Code

curl -X POST {{API_BASE_URL}}/employee-changes/demographic \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
    "address": {
      "line1": "456 New Street",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "90210"
    }
  }'

Compensation Change

Update an existing employee's compensation information including pay frequency, pay rate, or employment status.

POST /employee-changes/compensation-change

Request Payload

{
  "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
  "pay_frequency": "biweekly",
  "pay_rate": {
    "amount": "75000.00",
    "period": "annually",
    "effective_start": "2025-01-01"
  },
  "employment_status": "full_time"
}

Fields

Field	Type	Required	Description	Validation
`employee_id`	string	Yes	Employee ID	Required, min 1 character
`pay_frequency`	string	No	Pay frequency	Optional, `weekly`, `biweekly`, `semimonthly`, or `monthly`
`pay_rate`	object	No	Updated pay rate information	Optional, see Pay Rate fields below
`employment_status`	string	No	Employment status	Optional, `full_time`, `part_time`, or `variable_hours`

Pay Rate Fields

Field	Type	Required	Description	Validation
`amount`	string	Yes	Pay rate amount	Required, must be 0 or more, rounded to 2 decimal places (e.g., "75000.00")
`period`	string	Yes	Pay rate period	Required, `annually` or `hourly`
`effective_start`	string	Yes	When the pay rate becomes effective	Required, YYYY-MM-DD format

You can update any combination of pay frequency, pay rate, and employment status in a single request. All fields are optional, but at least one must be provided.

Sample Code

curl -X POST {{API_BASE_URL}}/employee-changes/compensation-change \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "emp_LRgFZ2uXBSVsR6Q0g9Q54",
    "pay_frequency": "biweekly",
    "pay_rate": {
      "amount": "75000.00",
      "period": "annually",
      "effective_start": "2025-01-01"
    },
    "employment_status": "full_time"
  }'