BAbamboohr
Benefits
Public API

Create Employee Dependent

Changed on

Creates a new dependent record for an employee. employeeId is required and must reference a valid employee. relationship must be a valid relationship type and gender must be a valid gender value. isUsCitizen and isStudent accept "yes" or "no". state accepts a state code (e.g. "UT") and country accepts an ISO 3166-1 alpha-2 country code (e.g. "US"). dateOfBirth must be in YYYY-MM-DD format. SSN and SIN are accepted as plain text and stored encrypted. Accepts both application/json and application/xml request bodies. The response format mirrors the request Content-Type (not the Accept header): JSON request bodies receive a JSON response; XML request bodies receive an XML response. A successful creation fires an internal dependent-created event that may trigger downstream benefit enrollment processing.

OAuth Scopes: employee:dependent.write, employee:dependent:ssn.write

post/api/v1/employeedependents

Request

Request body

employeeIdstring required

The internal employee ID of the employee this dependent belongs to. Required.

firstNamestring

The dependent's first name.

middleNamestring

The dependent's middle name.

lastNamestring

The dependent's last name.

relationshipstring

The dependent's relationship to the employee (e.g. "spouse", "child", "domestic_partner").

genderstring

The dependent's gender.

ssnstring

The dependent's Social Security Number, provided as plain text. Stored encrypted. Returned as a masked value (e.g. "xxx-xx-1234") on read.

sinstring

The dependent's Social Insurance Number (Canadian equivalent of SSN), provided as plain text. Stored encrypted. Returned as a masked value on read.

dateOfBirthstring date

The dependent's date of birth in YYYY-MM-DD format.

addressLine1string

The first line of the dependent's address.

addressLine2string

The second line of the dependent's address.

citystring

The dependent's city.

statestring

The dependent's state, provided as a state code (e.g. "UT"). Returned as a full state name on read.

zipCodestring

The dependent's ZIP or postal code.

homePhonestring

The dependent's home phone number.

countrystring

The dependent's country, provided as an ISO 3166-1 alpha-2 country code (e.g. "US"). Returned as a full country name on read.

isUsCitizen'yes' | 'no'

Whether the dependent is a US citizen. Accepted values: "yes" or "no".

isStudent'yes' | 'no'

Whether the dependent is currently a student. Accepted values: "yes" or "no".

Response

The newly created dependent record. Format matches the request Content-Type (JSON or XML).

Changes

  • 922fc15f43a7Revision changes
    • info

      the security scope employee:dependent:ssn.write was added to the endpoint's security scheme oauth

    • info

      the security scope employee:dependent.write was removed from the endpoint's security scheme oauth