Full JSON Schema for Creating & Updating Employees

📘
Note that this JSON schema body param differs subtly from the Employee object that is returned by the API. See the example JSON param given below for specific differences.

Required Fields

email
first_name
last_name
start_date (ONLY IF start date is required by Account Settings)
any custom_fields that are both internal and required

📘
If you are using Embedded mode, birthdate is required when creating Employees. In addition to the required fields, we recommend including the following:

address

SSN

phone (for Remote Authorized Representative Section)

For more details about fields, see the Employee Object page.

/* NOTE that all of the employee data must be wrapped in an "employee" key (Otherwise result is a 400): */
{  
  "employee": {
    "email": "emerald_keebler@hauck.name",  /* required! */
    "first_name": "Emerald",                /* required! */
    "middle_name": "J",
    "last_name": "Keebler",                 /* required! */
    "employee_type": "employee",            /* optional; uses account default if omitted */
    "birthdate": "1985-12-03",
    "phone": "844-555-1337",
    "address": {
      "street": "22061 Alexandria Common",
      "apt": "#12",
      "city": "Lake Khalil",
      "state": "ME",
      "zip": "44205",
      "country": "US"
    },
    "gender": "F",
    "nickname": "Emmy",
    "ssn": "123-45-6789",
    "groups": [3],                      /* Array of group IDs */
    "employment": {
      "start_date": "2015-10-09",       /* required if start date required enabled in Account Settings */
      "end_date": null,
      "hire_date": "2015-10-09",
      "onboarding_start_date": "2015-10-09",
      "status": "active"                /* defaults to 'active' if omitted */
    },
    "custom_fields": {                  /* Hash of Key-Value pairs (see below) */
      "udf_6": 12
    }
  }
}

`phone`

Must be between 7-14 digits. Only numbers, parentheses, hyphens, and spaces are accepted, e.g.:

phone: "1234567890"
phone: "(123) 456 7890"
phone: "123-456-7890"

`groups`

To add the new employee to groups as part of the creation process, simply provide the group IDs as an Array, e.g.:

"employee": {
  groups: [1, 2, 3]
}

If an invalid group ID is passed the request will still process correctly, however the employee will not be added to the invalid group.

`custom_fields`

To supply values for an employee's CustomFields, use the format udf_X for the key name, where X is the numeric ID of the custom field, e.g.:

"employee": {
  "custom_fields": {
    "udf_6": 12,
    "udf_193": "Director",
    "udf_11": true
  }
}

Custom field values must correspond to the following data types based on the field type:

Field Type(s)	JSON Data Type	Examples
TextField MultilineTextField	String	`"udf_X": "Some text.."`
DateField	String_ (format: `YYYY-MM-DD`)	`"udf_X": "1985-12-03"`
NumberField	Number_ (Integer)	`"udf_X": 5` `"udf_X": -10`
CurrencyField	Number_ (Decimal)	`"udf_X": 12.50`
DropdownField RadioField	String See FieldOptions object for more information on choice values.	`"udf_X": "Choice A"`
CheckboxField	Boolean	`"udf_X": true` `"udf_X": false`
MultiCheckboxField	Array of Strings	`"udf_X": ["Choice B", "Choice D"]`

`employment`

See Update Employment for details.

422 Errors

Occur in the following scenarios:

Not all required fields are included. The error message will describe the missing field.
Data is given in an invalid format. The error message will describe the nature of the error.
An employee is created with an email that exists in the organization. The error message will read: "This email already exists in your account and it belongs to: EMPLOYEE"

In each of these scenarios, the returned body will be a Hash called errors. The key is the field with the error, and the value is an array of strings containing the error message(s). See the given example for more.