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 (Non-Embedded)

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

Required Fields (Embedded)

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
address
phone (for Remote Authorized Representative Section)
SSN or applied_for_ssn
birthdate

📘
If you are using Embedded mode and you have the ability for employees to edit their demographic information enabled on the subdomain, the following fields are optional to provide when provisioning the employee:

address

birthdate

SSN or applied_for_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.

200200

400400

422422

500500