A Guide to People Information

Overview

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, including the Information, Contacts, Additional Information, Person's Dates, Process Profiles, and Access Profiles groups.

Create Person requests are executed using a JSON body with the following arrays:

user [Required] contains objects that define the user account information for a person.
personInformation [Required] contains objects that define important information about a person, including contact details, access profiles, process profiles, licenses, dates, and so forth.
personIdentity [Optional] contains properties and objects that define the core identifying elements of a person, including person and badge numbers.
jobAssignment [Required] contains properties and objects that define the job assignment information for a person.
gdapAssignments [Optional] contains an array with an object that defines the generic data access profile assignments for a person.

Basic example

In this example, we create a basic person entry using only the base information required to successfully create a record.

The request:

creates a user account, including user name, password, and a logon profile
defines information about the person, including name, hire date, and person number
adds a set of licenses, defining this person as an hourly Timekeeping employee
assigns a job, supervisor, and labor account

Example request

{
    "personInformation": {
        "person": {
            "birthDate": "1986-02-04", 
            "firstName": "Jane",
            "lastName": "Doe",
            "fullName": "Doe, Jane",
            "hireDate": "2019-08-15",
            "personNumber": "30197",
            "shortName": "JDoe"
        },
        "personLicenseTypes": [
            {
                "activeFlag": true,
                "licenseTypeName": "Employee"
            },
            {
                "activeFlag": true,
                "licenseTypeName": "Hourly Timekeeping"
            }
        ]
    },
    "jobAssignment": {
        "jobAssignmentDetails": {
            "payRuleName": "USCA-RT-PT",
            "supervisorName": "Morgan, Rebekah",
            "supervisorPersonNumber": "30165",
            "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": "JaneDoe",
            "userPassword": "3xAmp1em@rt"
        }
    }
}

Example response

The example 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": 50786
    },
    "personInformation": {
        "person": {
            "birthDate": "1986-02-04", 
            "firstName": "Jane",
            "lastName": "Doe",
            "fullName": "Doe, Jane",
            "hireDate": "2019-08-15",
            "personNumber": "30197",
            "shortName": "JDoe"
        },
        "personLicenseTypes": [
            {
                "activeFlag": true,
                "licenseTypeName": "Employee"
            },
            {
                "activeFlag": true,
                "licenseTypeName": "Hourly Timekeeping"
            }
        ]
    },
    "jobAssignment": {
        "jobAssignmentDetails": {
            "payRuleName": "USCA-RT-PT",
            "supervisorName": "Morgan, Rebekah",
            "supervisorPersonNumber": "30165",
            "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": "JaneDoe",
            "userPassword": "3xAmp1em@rt"
        }
    }
}

Assignments

Person Assignments allow you to make assignments of system entities for one or more persons.

Assignments are as varied as the system entities they represent, and while there are logical groupings of assignments that behave in similar ways, some assignments request and response models are very different from others.

Once you have mastered the skills covered in the first four topics, refer to the Guide to Person Assignments or the Guide to Aggregated Person Assignments for more information.