Create multiple person records

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

This operation allows 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:
- Log in to the UI
- Access their timecard
- Access their schedule
- Request time off
managers who can:
- Log in to the UI
- Access all of the same functions as employees
- View and edit employee timecards
- View and edit employee schedules
- Approve a time off request

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
creates a new, active manager named "Earl Grey"
- defines Earl's user name, password, authentication type, and work email address
- assigns Earl a job, a base wage, basic licenses, a display profile, and a labor account

[
  {
    "personInformation": {
      "accessAssignment": {
        "accessProfileName": "Retail Manager",
        "managerPayCodeName": "Retail Pay Codes",
        "managerViewPayCodeName": "Retail Pay Codes",
        "managerWorkRuleName": "Retail Work Rules",
        "notificationProfileName": "All",
        "preferenceProfileName": "Retail DP",
        "professionalPayCodeName": "Retail Pay Codes",
        "professionalWorkRuleName": "Retail Work Rules",
        "shiftCodeName": "Retail Templates"
      },
      "emailAddresses": [
        {
          "address": "[email protected]",
          "contactTypeName": "Work",
          "hasEmailNotificationDelivery": true
        }
      ],
      "employmentStatusList": [
        {
          "effectiveDate": "2019-08-13",
          "employmentStatusName": "Active",
          "expirationDate": "3000-01-01"
        }
      ],
      "person": {
        "birthDate": "1986-02-04",
        "firstName": "Earl",
        "lastName": "Grey",
        "fullName": "Grey, Earl",
        "hireDate": "2016-08-13",
        "personNumber": "2001",
        "shortName": "EGrey"
      },
      "personAuthenticationTypes": [
        {
          "activeFlag": true,
          "authenticationTypeName": "Basic"
        }
      ],
      "personLicenseTypes": [
        {
          "activeFlag": true,
          "licenseTypeName": "Employee"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Manager"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Absence"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Workforce MobileManager"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Workforce TabletManager"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Hourly Timekeeping"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Scheduling"
        }
      ],
      "userAccountStatusList": [
        {
          "effectiveDate": "2016-08-13",
          "expirationDate": "3000-01-01",
          "userAccountStatusName": "Active"
        }
      ]
    },
    "jobAssignment": {
      "baseWageRates": [
        {
          "effectiveDate": "1753-01-01",
          "expirationDate": "3000-01-01",
          "hourlyRate": 42.15
        }
      ],
      "jobAssignmentDetails": {
        "payRuleName": "USNY-RT-FT",
        "timeZoneName": "(GMT -05:00) Eastern Time"
      },
      "primaryLaborAccounts": [
        {
          "effectiveDate": "2019-08-13",
          "expirationDate": "3000-01-01",
          "organizationPath": "Organization/United States/Metropolitan Store/California/Example Mart/Admin/Store Manager"
        }
      ]
    },
    "user": {
      "userAccount": {
        "userName": "EarlGrey",
        "userPassword": "3x@mplE1"
      }
    },
    "gdapAssignments": [
      {
        "defaultSwitch": true,
        "effectiveDate": "2019-08-15",
        "expirationDate": "3000-01-01",
        "role": "MANAGER_ROLE",
        "gdapName": "Retail Manager GDAP"
      }
    ]
  },
  {
    "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": "1234567",
        "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

Since the JSON is processed sequentially, if you are passing people who report to other people being created in the same request, you must specify the supervisors (in order of hierarchy, from highest to lowest) before you specify employees who report to those supervisors.
The organization path of each person record'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 Persons POST /v1/commons/persons/multi_create operation for descriptions of each object, array, and property.
The structure for each record passed in this request exactly matches the individual structure passed in a Create Person GET /v1/commons/persons request.

Example response

The response is an array containing the created person records, each of which now contains the personIdentity array which has one property: a system-generated ID, known as a person key or employee ID. The response otherwise mimics the successful request body.

[
  {
    "personIdentity": {
      "personKey": 50800
      },
    "personInformation": {
      "accessAssignment": {
        "accessProfileName": "Retail Manager",
        "managerPayCodeName": "Retail Pay Codes",
        "managerViewPayCodeName": "Retail Pay Codes",
        "managerWorkRuleName": "Retail Work Rules",
        "notificationProfileName": "All",
        "preferenceProfileName": "Retail DP",
        "professionalPayCodeName": "Retail Pay Codes",
        "professionalWorkRuleName": "Retail Work Rules",
        "shiftCodeName": "Retail Templates"
      },
      "emailAddresses": [
        {
          "address": "[email protected]",
          "contactTypeName": "Work",
          "hasEmailNotificationDelivery": true
        }
      ],
      "employmentStatusList": [
        {
          "effectiveDate": "2019-08-13",
          "employmentStatusName": "Active",
          "expirationDate": "3000-01-01"
        }
      ],
      "person": {
        "birthDate": "1986-02-04",
        "firstName": "Earl",
        "lastName": "Grey",
        "fullName": "Grey, Earl",
        "hireDate": "2016-08-13",
        "personNumber": "2001",
        "shortName": "EGrey"
      },
      "personAuthenticationTypes": [
        {
          "activeFlag": true,
          "authenticationTypeName": "Basic"
        }
      ],
      "personLicenseTypes": [
        {
          "activeFlag": true,
          "licenseTypeName": "Employee"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Manager"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Absence"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Workforce MobileManager"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Workforce TabletManager"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Hourly Timekeeping"
        },
        {
          "activeFlag": true,
          "licenseTypeName": "Scheduling"
        }
      ],
      "userAccountStatusList": [
        {
          "effectiveDate": "2016-08-13",
          "expirationDate": "3000-01-01",
          "userAccountStatusName": "Active"
        }
      ]
    },
    "jobAssignment": {
      "baseWageRates": [
        {
          "effectiveDate": "1753-01-01",
          "expirationDate": "3000-01-01",
          "hourlyRate": 42.15
        }
      ],
      "jobAssignmentDetails": {
        "payRuleName": "USNY-RT-FT",
        "timeZoneName": "(GMT -05:00) Eastern Time"
      },
      "primaryLaborAccounts": [
        {
          "effectiveDate": "2019-08-13",
          "expirationDate": "3000-01-01",
          "organizationPath": "Organization/United States/Metropolitan Store/California/Example Mart/Admin/Store Manager"
        }
      ]
    },
    "user": {
      "userAccount": {
        "userName": "EarlGrey",
        "userPassword": "3x@mplE1"
      }
    },
    "gdapAssignments": [
      {
        "defaultSwitch": true,
        "effectiveDate": "2019-08-15",
        "expirationDate": "3000-01-01",
        "role": "MANAGER_ROLE",
        "gdapName": "Retail Manager GDAP"
      }
    ]
  },
  {
    "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 configuring additional parameters for a person, proceed to the Configure access topic.