Update Employee

JSON Schema for Body

Use the same JSON schema as documented in the Create Employee API. You do not have to supply all fields – only data which you provide will be updated. To clear a field, pass null.

Some things to watch out for:

groups

The IDs passed via groups in an Update Employee request will replace all of the employee's existing group memberships (i.e. it is a "replace," not an "upsert"). It must be an Array of IDs, or an empty Array.

To add an employee to a group while preserving existing memberships, use the Add Employee to Group endpoint instead.

If you don't wish to modify existing group memberships, omit the groups key altogether from the JSON body. Passing an empty Array ([]) will effectively remove the employee from all groups.

If groups are altered, form assignments will be altered accordingly.

custom_fields

A custom field value will only change if that field is included in the custom_fields object. All other omitted custom field IDs will be left untouched in the employee's record. For example, the following JSON will only update the value for custom field with ID "1"; other custom field values for this employee will be left alone.

{
  "employee": { 
    "custom_fields": { 
      "udf_1": 5,
    }
  }
}

To clear ALL field data, you must include each individual field with value of null (i.e. you cannot clear en masse).

🚧

Caution: "udf_X required" even though you weren't trying to update "udf_X"

Even though only the fields you provide will be updated, all existing custom field data for that employee will still be validated.

The most common situation where this comes up is when you have a Required, Internal custom field whose value is blank for this employee (e.g. if the field is brand new, or an existing field's settings have been changed so the field is now required and internal). Even though you are not including this particular field in your Update Employee API call, the API still complains about it – you get a 422 response with the following validation error message:

JSON

 { 
  "errors": {
    "custom_fields": {
      "udf_16": ["You must select at least one option from the dropdown checklist."],
      "udf_17": ["This field is required."]			// This is the required internal field
    }
  }
}

This may change in the future, but at this time, there is no way around this – you must supply a value, either with your API call or through the application itself. This is the same level of validation that admins experience in the app when adding a new employee or editing Custom Fields via the UI.

NOTE: Non-internal custom fields are expected to be completed by the employee and so their presence will not be enforced by the API.