Create an employee

Example requests are POSTed to the Create Person URL:
https://<<hostName>>/api/v1/commons/persons

The Create Person (POST /v1/commons/persons) and Create Persons (POST /v1/commons/persons/multi_create) operations allow you to create new people entries in the system and to pass information that corresponds to the options in the Maintenance > People Information > Employee section of the user interface.

By following this example, you will be able to create employees who can perform basic necessary actions, such as:

Log in to the UI
Access their timecard
Access their schedule
Request time off

Example request
Example response
Next steps

Example request

In this example, the request:

creates a new, active employee named "Roger Wilco"
defines Roger's user name, password, authentication type, and work email address
assigns Roger a job, a manager, a base wage, basic licenses, a display profile, and a labor account

{
  "personInformation": {
    "accessAssignment": {
      "accessProfileName": "Retail Employee",
      "notificationProfileName": "All",
      "preferenceProfileName": "Retail Employee DP",
      "professionalPayCodeName": "Retail Pay Codes",
      "professionalWorkRuleName": "Retail Work Rules",
      "shiftCodeName": "Retail Templates"
    },
    "emailAddresses": [
      {
        "address": "[email protected]",
        "contactTypeName": "Work",
        "hasEmailNotificationDelivery": true
      }
    ],
    "employmentStatusList": [
      {
        "effectiveDate": "2019-08-15",
        "employmentStatusName": "Active",
        "expirationDate": "3000-01-01"
      }
    ],
    "person": {
      "birthDate": "1986-02-04",
      "firstName": "Roger",
      "lastName": "Wilco",
      "fullName": "Wilco, Roger",
      "hireDate": "2019-08-15",
      "personNumber": "123456",
      "shortName": "RWilco"
    },
    "personAuthenticationTypes": [
      {
        "activeFlag": true,
        "authenticationTypeName": "Basic"
      }
    ],
    "personLicenseTypes": [
      {
        "activeFlag": true,
        "licenseTypeName": "Employee"
      },
      {
        "activeFlag": true,
        "licenseTypeName": "Absence"
      },
      {
        "activeFlag": true,
        "licenseTypeName": "Hourly Timekeeping"
      },
      {
        "activeFlag": true,
        "licenseTypeName": "Scheduling"
      }
    ],
    "userAccountStatusList": [
      {
        "effectiveDate": "2019-08-15",
        "expirationDate": "3000-01-01",
        "userAccountStatusName": "Active"
      }
    ]
  },
  "jobAssignment": {
    "baseWageRates": [
      {
        "effectiveDate": "2019-01-01",
        "expirationDate": "3000-01-01",
        "hourlyRate": 20.15
      }
    ],
    "jobAssignmentDetails": {
      "payRuleName": "USNY-RT-FT",
      "supervisorName": "Grey, Earl",
      "supervisorPersonNumber": "2001",
      "timeZoneName": "(GMT -05:00) Eastern Time"
    },
    "primaryLaborAccounts": [
      {
        "effectiveDate": "2019-08-15",
        "expirationDate": "3000-01-01",
        "organizationPath": "Organization/United States/Metropolitan Store/New York/Example Mart/Retail/Cashier"
      }
    ]
  },
  "user": {
    "userAccount": {
      "logonProfileName": "Professional Hourly Employee",
      "userName": "RogerWilco",
      "userPassword": "3x@mpl3"
    }
  }
}

Notes of interest

The organization path of your employee's primary labor account must be a job in your organization's business structure.
For date properties, the values for the earliest possible date (also known as the "beginning of time") and the latest possible date (also known as the "end of time") are 1900-01-01 and 3000-01-01, respectively.
Refer to the Resource Details of the Create Person GET /v1/commons/persons or Create Persons POST /v1/commons/persons/multi_create operation for descriptions of each object, array, and property.
You cannot assign a supervisor to an employee or manager unless that supervisor already exists in the system or is specified first in a multi-create request payload.

Example response

The response adds the personIdentity array containing one property: a system-generated ID, known as a person key or employee ID. The response otherwise mimics the successful request body.

{
  "personIdentity": {
    "personKey": 50801
    },
  "personInformation": {
    "accessAssignment": {
      "accessProfileName": "Retail Employee",
      "notificationProfileName": "All",
      "preferenceProfileName": "Retail Employee DP",
      "professionalPayCodeName": "Retail Pay Codes",
      "professionalWorkRuleName": "Retail Work Rules",
      "shiftCodeName": "Retail Templates"
    },
    "emailAddresses": [
      {
        "address": "[email protected]",
        "contactTypeName": "Work",
        "hasEmailNotificationDelivery": true
      }
    ],
    "employmentStatusList": [
      {
        "effectiveDate": "2019-08-15",
        "employmentStatusName": "Active",
        "expirationDate": "3000-01-01"
      }
    ],
    "person": {
      "birthDate": "1986-02-04",
      "firstName": "Roger",
      "lastName": "Wilco",
      "fullName": "Wilco, Roger",
      "hireDate": "2019-08-15",
      "personNumber": "123456",
      "shortName": "RWilco"
    },
    "personAuthenticationTypes": [
      {
        "activeFlag": true,
        "authenticationTypeName": "Basic"
      }
    ],
    "personLicenseTypes": [
      {
        "activeFlag": true,
        "licenseTypeName": "Employee"
      },
      {
        "activeFlag": true,
        "licenseTypeName": "Absence"
      },
      {
        "activeFlag": true,
        "licenseTypeName": "Hourly Timekeeping"
      },
      {
        "activeFlag": true,
        "licenseTypeName": "Scheduling"
      }
    ],
    "userAccountStatusList": [
      {
        "effectiveDate": "2019-08-15",
        "expirationDate": "3000-01-01",
        "userAccountStatusName": "Active"
      }
    ]
  },
  "jobAssignment": {
    "baseWageRates": [
      {
        "effectiveDate": "2019-01-01",
        "expirationDate": "3000-01-01",
        "hourlyRate": 20.15
      }
    ],
    "jobAssignmentDetails": {
      "payRuleName": "USNY-RT-FT",
      "supervisorName": "Grey, Earl",
      "supervisorPersonNumber": "2001",
      "timeZoneName": "(GMT -05:00) Eastern Time"
    },
    "primaryLaborAccounts": [
      {
        "effectiveDate": "2019-08-15",
        "expirationDate": "3000-01-01",
        "organizationPath": "Organization/United States/Metropolitan Store/New York/Example Mart/Retail/Cashier"
      }
    ]
  },
  "user": {
    "userAccount": {
      "logonProfileName": "Professional Hourly Employee",
      "userName": "RogerWilco",
      "userPassword": "3x@mpl3"
    }
  }
}

Next steps

To learn about creating a person with the manager role, proceed to the Create a manager topic.

Contents

Example request

Example response

Next steps