The Upsert Employee endpoint is used both to create new employees and to update existing employees.
New Employee Invitation/Activation
If the email, zipCode, ssnLastFour, and birthDate fields are set when a new Employee is created, WFH will automatically send an invitation email to the employee allowing them to activate their account and set their password. If fields are not set on creation, then the password will need to be set in the WFH UI, and you will need to provide the employee with their login URL and password.
Required Employee Fields
When creating a new Employee, the following fields are required:
- firstName
- lastName
- email – must be unique among all Employees in the Company
- originalHireDate
When updating an Employee, the employeeCode or employeeId is required.
Employee Field Validation
If provided, these fields must match certain formats:
- ssnLastFour – ####
- ssn – ###-##-####
- zipCode – #####
- state – Must be one of the 50 standard two-character US state codes, as well as ‘DC’ for the District of Columbia. Use the Get States endpoint to get valid state codes.
- Phone – ###-###-####, (###) ###-####
Partial Employee Updates
The WFH API will compare the incoming Employee data against any existing Employee data, and only update those fields that are defined in the sent payload. This means that you do not need to define all fields in the Employee schema when updating an Employee, you can just define the ones you want to update.
Sample Upsert Employee API Call
Suppose an external payroll system has created a new employee that we want to sync to WFH. The external system’s Employee identifier for this Employee is “EMP042”, and our Client Company has a Site ID of 79701. In this example, we could send the employee to WFH using this API call:
POST https://api.workforcehub.com/api/employee
Authorization: Bearer <API auth token>
x-api-version: 1.0
x-integration-partner-id: <provided id>
Content Body:
{
"employeeCode": "WM12345",
"firstName": "William",
"email": "billy.maizer@example.com",
"homeDepartment": [
{
"effectiveDate": "2022-02-21T05:00:00",
"organization": {
"name": "Software Development",
"organizationType": "Department"
}
}
]
}
Later we could update changes to this Employee’s data with the same API call:
POST https://api.workforcehub.com/api/employee
Authorization: Bearer <API auth token>
x-api-version: 1.0
x-integration-partner-id: <provided id>
Content Body:
{
"employeeCode": "WM12345",
"homeDepartment": [
{
"effectiveDate": "2022-03-21T05:10:00",
"organization": {
"name": "Engineering",
"organizationType": "Department"
}
}
]
}