Create Employee

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, we recommend creating Employees with the following fields in addition to the required fields:

• birthdate
• 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": "[email protected]",  /* 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:

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.