# Quick Start: Create an Employee

When creating an employee with the Employee API v2, some preparation work needs to be done first. We'll need to request for localized metadata about your employees that will give us back an ID we'll pass for the following items:

  • Termination Reasons
  • Employment Status
  • Leave Reasons
  • Employment Categories
  • Custom Relations
  • Custom Fields

Obviously, not all of these are required for creating every employee (termination reasons, for example), and your organization may not use all of them. However, when creating an employee, we will most likely need to fetch something first. Thus, the steps are:

  1. Get the relevant employee metadata (for this example, we'll be using custom fields).
  2. Post a new employee.

# Step 1: Get the relevant employee metadata

We'll start by requesting a list of all employee custom fields. If you have many custom fields, this could be multiple calls.

GET /services/api/x/users/v2/employees/custom-fields
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

From the response, notice the id of "Degree" dropdown custom field which we'll be using. Also, notice the id of the "Undergrad" option.

// 200 OK
[
{
"id": 36,
"name": "Nickname",
"required": false,
"type": "ShortTextBox",
},
{
"id": 37,
"name": "Degree",
"required": true,
"type": "Dropdown",
"options": [
{
"id": 123938,
"title": "None"
},
{
"id": 123939,
"title": "High School"
},
{
"id": 123919,
"title": "Undergrad"
},
{
"id": 123902,
"title": "Postgrad"
}
]
}

# Step 2: Create the employee

Once we've fetched our custom fields, we can build our request to create an employee.

For this example, we'll create an employee Thomas Smith, nickname Tom, with an Undergrad degree. In the example below, you will notice that we have included Tom's manager's ID as well as his OUs. You can fetch these IDs by following the examples in the Quick Start: Get an Employee and Quick Start: Get an OU sections.

POST /services/api/x/users/v2/employees/
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

{
    "externalId": "tsmith482",
    "userName": "thomas.smith",
    "firstName": "Thomas",
    "lastName": "Smith",
    "middleName": "Paul",
    "primaryEmail": "t@smith.com",
    "workPhone": "3105551234",
    "address": {
        "country": "US",
        "line1": "1601 Cloverfield Blvd",
        "city": "Santa Monica",
        "state": "CA",
        "zipCode": "90404"
    },
    "settings": {
        "displayLanguage": "es-ES",
        "timeZone": "(UTC-12:00) International Date Line West"
    },
    "managerId": 37,
    "ous": [
        {
            "id": 40950,
            "typeId": 2
        }
    ],
    "customFields": [
        {
            "id": 37,
            "value": "123919"
        }
    ]
}

When we're able to successfully create an employee, we'll receive a success message, with the newly created employee's ID and link to get details.

// 201 Created
{
    "id": 48928,
    "links": {
        "href": "/v2/employees/48928"
    }
}