Pending Hire Service

Pending Hire Service API

The UKG Pro Pending Hire Service API enables you to load pending hire information into UKG Pro for processing.

Note: Most of the core employee data field lengths are increased to match UKG Pro global data length.

Overview

This document describes the methods of the service and provides examples.

The following information describes the service requirements.

Service Specifications
ProtocolHTTP (REST)
SSL SupportRequired
Signup and Licensing
Account RequiredUKG Pro Web Service Account or UKG Pro Web User with Web Services Permissions

Using an UKG Pro Web Service Account is recommended. For information regarding establishing and maintaining an UKG Pro Web Service Account, please refer to the document Manage Service Accounts located in the UKG Pro Learning Center Home > Documentation > System Management > Integrate > Web Services.

Pending Hire Data

Pending Hire data is included in the table.

Property Required Min Length Max Length Notes
Pending Hire Detail
Id See Notes

Required if updating a record
OfferId N
15
RequisitionId N
50
ImportedBy N
30
ImportDate -

Read only from GET
EmployeeHire Data
CompanyId N 5 5
SsnOrSin N 0 50
SinExpirationDate N


NamePrefixCode N
50 UKG Pro Code (PREFIX)
NameFirst Y 1 100
NameMiddle N 1 50
NameLast Y 1 100
NamePreferred N 1 100
NameSuffixCode N 1 50 UKG Pro Code (SUFFIX)
FormerLastname N 0 100
EmployeeNumber N 1 9
TimeclockId N
12
AddressLine1 N 1 255
AddressLine2 N 1 255
City N 1 255
StateOrProvinceCode N 0 255
ZipOrPostalCode N 0 50
AddressCounty N 0 255
AddressCountryCode N 0 3
MailStop N 0 10
HomePhoneNumber N 0 50
BusinessPhoneNumber N 0 10
BusinessPhoneExtension N 0 5
OtherPhoneNumber N 0 50
OtherPhoneTypeCode N 1 50 UKG Pro Code (OTHERPHONE)
PrimaryEmailAddress N 1 50
AlternateEmailAddress N 1 50
DateOfBirth N

1/1/1881 – 12/31/2199
GenderCode N 1 50 UKG Pro Code (GENDER)
MaritalStatusCode N 1 50 UKG Pro Code (MARITALSTATUS)
EthnicCode N 1 50 UKG Pro Code (ETHNICCODE2007)
I9VerifiedCode N 1 50 UKG Pro Code (I9VERIF)
StartDate N

1/1/1881 – 12/31/2199
DateOfOriginalHire N

1/1/1881 – 12/31/2199
DateOfSeniority N

1/1/1881 – 12/31/2199
DateOfBefefitSeniority N

1/1/1881 – 12/31/2199
Supervisor N

Employee Identifier

Sample:

Supervisor":{

"Type": "Ssn",

"Value": "369852147",

"CompanyIdentifier": null

}


Types available:

EmployeeId

EmployeeNumber

EmailAddress

Ssn

Sin

NationalId

JobGroupCode N
5 UKG Pro Code (JOBGRP)
JobCode See Notes

UKG Pro Code (JOBCODEBYCOUNTRY)

Either JobCode or JobTitle is required for companies that are not position-managed.

If the JobCode is provided and the company is position-managed, the JobCode must match a look-up of the correct JobCode associated with the PositionCode provided.

JobTitle See Notes

LocationCode N 1 6 UKG Pro Code (TAXPRIMARYLOCATION)
HireSourceCode N 1 6 UKG Pro Code (HIRESRCE)
OrgLevel1Code N 1 6 UKG Pro Code (ORGLVL1)
OrgLevel2Code N 1 6 UKG Pro Code (ORGLVL2)
OrgLevel3Code N 1 6 UKG Pro Code (ORGLVL3)
OrgLevel4Code N 1 6 UKG Pro Code (ORGLVL4)
PayRate N 1 Decimal Max 0.0 - 999999999.99
RatePerCode N 1 50 UKG Pro Code (RATESPER)
PayGroupCode N 1 6 UKG Pro Code (PAYGROUPBYCOMP)
ScheduledWorkHours N 0.0 99999999.0 0.0 - 99999999.0000
PaymentsPerYear N Int.Min Int.Max
WeeklyHours N 0.0 168.0
EarningsGroupCode N 1 5 UKG Pro Code (EARNGRP)
DeductionBenefitGroupCode N 1 5 UKG Pro Code (BENGRP)
EmployeeTypeCode N 1 50 UKG Pro Code (EMPTYPE)
HourlyOrSalaryCode N 1 50 UKG Pro Code (SALARYORHOURLY)
FullTimeOrPartTimeCode N 1 50 UKG Pro Code (FULLORPARTTIME)
ShiftCode N 1 2

UKG Pro Code

(SHIFTSBYJOBANDGROUP)

PositionCode N 1 8 UKG Pro Code (POSITION)
PersonId N Guid Guid UKG Pro PersonId to Use Onb10 Integration Only

Supplemental Data

Although supplemental data is not required and the section may be omitted, if you choose to submit supplemental data, there may be certain requirements that apply. These requirements are included below.

CandidateInfo
MilitaryEraCode N
50 UKG Pro Code (MILITARYERA)
MilitaryBranchServedCode N
50 UKG Pro Code (MILITARY)
IsDisabled Y

Yes/No/Decline
IsVeteran Y

Yes/No/Decline
SeparationDate N

1/1/1881 > 12/31/2199
IsArmedForcesServiceMedal N

Yes/No/Decline
IsSpecialDisabledVeteran N

Yes/No/Decline
IsActiveWarTimeVet N

Yes/No/Decline
Education Info
SchoolCode Y
50 UKG Pro Code (SCHOOL)
FromDate N

1/1/1881 – 12/31/2199
ToDate N

1/1/1881 – 12/31/2199
Graduated N

True/False
Years N

0 – Int32.MaxValue
MajorCode N
50 UKG Pro Code (EDUCMAJOR)
MinorCode N
50 UKG Pro Code (EDUCMAJOR)
Location N
20
LevelCode N
50 UKG Pro Code (EDUCLEVEL)
Gpa N

0 – 99999
Rank N

0 – 999999
Notes N 1 32,767 Characters for length.
Experience Info
Employer Y 1 30
FromDate Y From Date should be less then To date 1/1/1881 – 12/31/2199
ToDate Y 1/1/1881 – 12/31/2199
Position No 1 30
Location No 1 20
Salary No See Notes

0 - 9999999999999.9

Required if SalaryPerCode is provided.

SalaryPerCode No See Notes

UKG Pro Code (SALARYPER)

Required if Salary is provided.

ReasonForLeaving No 1 25
Notes
1 32,767 Character Length
License Info
LicenseCode Y
6 UKG Pro Code (LICENSE)
LicenseNumber No 1 20
ReceivedDate No

1/1/1881 – 12/31/2199
RenewalDate No

1/1/1881 – 12/31/2199
ProviderCode No
6 UKG Pro Code (CAREPROVIDER)
Skill Info
SkillCode Y
6 UKG Pro Codes (SKILLS)
ProficiencyCode No
6 UKG Pro Codes (PROFICIENCY)
AssessedOnDate No See Notes

1/1/1881 – 12/31/2199

Required if AssessedBy is provided.

AssessedBy No 1 20 Required if AssessedOnDate is provided.
Notes No 1 32,767 Character length

Pending Hire Service

Header

To initially log in to the Pending Hire web service, the username and password for the UKG Pro Web Service Account or UKG Pro Web User can be sent for basic authorization. The format is username:password. Use a colon between the username and password. Credentials in this format must then be encoded using standard base64 encoding. The initial call to the service should contain a header as follows:

Basic Auth Example

Authorization: basic dXNlcm5hbWU6cGFzc3dvcmQ=

Accept: application/json

Content-Type: application/json

US-Customer-Api-Key: <YOUR COMPANY’S API KEY>

The return from this call will contain a US-SessionId. This token should be included in the header of subsequent calls to the service.

Example

US-SessionId: 1807a7d3-1fdd-4c14-835b-59b178a323ec

Accept: application/json

Content-Type: application/json

US-Customer-Api-Key: <YOUR COMPANY’S API KEY>

Pending Hire Data - GET

Pending hire data using the GET statement is included in this section.

ParameterDescription
GETReturns the Pending Hire records that have not yet been processed in UKG Pro

Resource URL: https://servername/services/employeehire/v1/pendinghires

Sample Return from GET

{
    "odata.metadata": " https://servername/services/employeehire/v1/pendinghires /$metadata#employeependinghires",
    "value": [
        {
            "Id": 5,
            "OfferId": "               ",
            "RequisitionId": "",
            "ImportDate": "2013-08-09T10:46:28.343",
            "EmployeeHireData": {
                "CompanyId": "0ZVY7",
                "SsnOrSin": null,
                "NamePrefixCode": "Mr",
                "NameFirst": "Bruce",
                "NameMiddle": null,
                "NameLast": "Wayne",
                "NameSuffixCode": "Jr",
                "EmployeeNumber": null,
                "TimeclockId": null,
                "AddressLine1": "Wayne Manor",
                "AddressLine2": null,
                "City": "Gotham City",
                "StateOrProvinceCode": "NJ",
                "ZipOrPostalCode": "12345",
                "HomePhoneNumber": "7555551212",
                "BusinessPhoneNumber": null,
                "BusinessPhoneExtension": null,
                "OtherPhoneNumber": null,
                "OtherPhoneTypeCode": null,
                "PrimaryEmailAddress": null,
                "AlternateEmailAddress": null,
                "DateOfBirth": null,
                "GenderCode": "M",
                "MaritalStatusCode": null,
                "EthnicCode": "1",
                "I9VerifiedCode": null,
                "StartDate": null,
                "JobGroupCode": null,
                "JobCode": "SUPPORT",
                "JobTitle": "",
                "LocationCode": "PALOCA",
                "HireSourceCode": null,
                "OrgLevel1Code": null,
                "OrgLevel2Code": null,
                "OrgLevel3Code": null,
                "OrgLevel4Code": null,
                "PayRate": "56789.1234",
                "RatePerCode": "Y",
                "PayGroupCode": null,
                "ScheduledWorkHours": null,
                "EarningsGroupCode": null,
                "DeductionBenefitGroupCode": null,
                "EmployeeTypeCode": null,
                "HourlyOrSalaryCode": "S",
                "FullTimeOrPartTimeCode": "P",
                "ShiftCode": null,
                "PositionCode": null
            },
            "SupplementalData": {
                "CandidateInfo": {
                    "MilitaryEraCode": null,
                    "MilitaryBranchServedCode": null,
                    "IsDisabled”:”Y/N",
                    "IsVeteran”:”Y/N"
                },
                "EducationInfo": [],
                "ExperienceInfo": [
                    {
                        "Employer": "ACME",
                        "FromDate": "2010-02-01T00:00:00",
                        "ToDate": "2012-04-01T00:00:00",
                        "Position": "Gardener",
                        "Location": "New York",
                        "Salary": null,
                        "SalaryPerCode": null,
                        "ReasonForLeaving": null,
                        "Notes": "Picked grass"
                    }
                ],
                "LicenseInfo": [
                    {
                        "LicenseCode": "MCNE",
                        "LicenseNumber": "1234",
                        "ReceivedDate": "2011-02-01T00:00:00",
                        "RenewalDate": "2014-02-01T00:00:00",
                        "ProviderCode": null
                    }
                ],
                "SkillInfo": [
                    {
                        "SkillCode": "ACT",
                        "ProficiencyCode": "NOV",
                        "AssesedOnDate": null,
                        "AssessedBy": null,
                        "Notes": null
                    }
                ]
            }
        },
        {
            "Id": 6,
            "OfferId": "               ",
            "RequisitionId": "",
            "ImportDate": "2013-08-09T11:47:11.2",
            "EmployeeHireData": {
                "CompanyId": "C0014",
                "SsnOrSin": null,
                "NamePrefixCode": "Mr",
                "NameFirst": "Peter",
                "NameMiddle": "Spiderman",
                "NameLast": "Parker",
                "NameSuffixCode": null
                "EmployeeNumber": null,
                "TimeclockId": null,
                "AddressLine1": "123 Maple Lane",
                "AddressLine2": null,
                "City": "New York",
                "StateOrProvinceCode": "NY",
                "ZipOrPostalCode": "12345",
                "HomePhoneNumber": "7555551213",
                "BusinessPhoneNumber": , "7555551214",
                "BusinessPhoneExtension": null,
                "OtherPhoneNumber": "7555551215",
                "OtherPhoneTypeCode": "CEL",,
                "PrimaryEmailAddress": "[email protected]",
                "AlternateEmailAddress": null,
                "DateOfBirth": null,
                "GenderCode": "M",
                "MaritalStatusCode": null,
                "EthnicCode": "5",
                "I9VerifiedCode": null,
                "StartDate": null,
                "JobGroupCode": null,
                "JobCode": "EXEC",
                "JobTitle": "Executive",
                "LocationCode": "NYC",
                "HireSourceCode": null,
                "OrgLevel1Code": null,
                "OrgLevel2Code": null,
                "OrgLevel3Code": null,
                "OrgLevel4Code": null,
                "PayRate": "58000.00",
                "RatePerCode": "Y",
                "PayGroupCode": null,
                "ScheduledWorkHours": null,
                "EarningsGroupCode": null,
                "DeductionBenefitGroupCode": null,
                "EmployeeTypeCode": null,
                "HourlyOrSalaryCode": "S",
                "FullTimeOrPartTimeCode": "F",
                "ShiftCode": null,
                "PositionCode": null
            },
            "SupplementalData": null
        }
    ]
}

Pending Hire Data - GET with Record ID

The Pending Hire Data using GET with Record ID is included in this section.

ParametersDescription

GET with Record ID

(Optional)

Filters the return to include only the Pending Hire record with the ID number indicated as the ID parameter.

Resource URL: https://servername/services/employeehire/v1/pendinghires(5)

Sample Return from GET with Record ID

{
    "odata.metadata": " https://servername/services/employeehire/v1/$metadata#pendinghires/@Element",    
	"Id": 5,
    "OfferId": "               ",
    "RequisitionId": "",
    "ImportDate": "2013-08-09T10:46:28.343",
    "EmployeeHireData": {
        "CompanyId": "0ZVY7",
        "SsnOrSin": null,
        "NamePrefixCode": "Mr",
        "NameFirst": "Bruce",
        "NameMiddle": null,
        "NameLast": "Wayne",
        "NameSuffixCode": "Jr",
        "EmployeeNumber": null,
        "TimeclockId": null,
        "AddressLine1": "Wayne Manor",
        "AddressLine2": null,
        "City": "Gotham City",
        "StateOrProvinceCode": "NJ",
        "ZipOrPostalCode": "12345",
        "HomePhoneNumber": "7555551212",
        "BusinessPhoneNumber": null,
        "BusinessPhoneExtension": null,
        "OtherPhoneNumber": null,
        "OtherPhoneTypeCode": null,
        "PrimaryEmailAddress": null,
        "AlternateEmailAddress": null,
        "DateOfBirth": null,
        "GenderCode": "M",
        "MaritalStatusCode": null,
        "EthnicCode": "1",
        "I9VerifiedCode": null,
        "StartDate": null,
        "JobGroupCode": null,
        "JobCode": "SUPPORT",
        "JobTitle": "",
        "LocationCode": "PALOCA",
        "HireSourceCode": null,
        "OrgLevel1Code": null,
        "OrgLevel2Code": null,
        "OrgLevel3Code": null,
        "OrgLevel4Code": null,
        "PayRate": "56789.1234",
        "RatePerCode": "Y",
        "PayGroupCode": null,
        "ScheduledWorkHours": null,
        "EarningsGroupCode": null,
        "DeductionBenefitGroupCode": null,
        "EmployeeTypeCode": null,
        "HourlyOrSalaryCode": "S",
        "FullTimeOrPartTimeCode": "P",
        "ShiftCode": null,
        "PositionCode": null
    },
    "SupplementalData": {
        "CandidateInfo": {
            "MilitaryEraCode": null,
            "MilitaryBranchServedCode": null
        },
        "EducationInfo": [],
        "ExperienceInfo": [
            {
                "Employer": "ACME",
                "FromDate": "2010-02-01T00:00:00",
                "ToDate": "2012-04-01T00:00:00",
                "Position": "Gardener",
                "Location": "New York",
                "Salary": null,
                "SalaryPerCode": null,
                "ReasonForLeaving": null,
                "Notes": "Picked grass"
            }
        ],
        "LicenseInfo": [
            {
                "LicenseCode": "MCNE",
                "LicenseNumber": "1234",
                "ReceivedDate": "2011-02-01T00:00:00",
                "RenewalDate": "2014-02-01T00:00:00",
                "ProviderCode": null
            }
        ],
        "SkillInfo": [
            {
                "SkillCode": "ACT",
                "ProficiencyCode": "NOV",
                "AssesedOnDate": null,
                "AssessedBy": null,
                "Notes": null
            }
        ]
    }
}

Pending Hire Data - POST

The Pending Hire data using POST is included in this section.

ParameterDescription
POSTInserts a Pending Hire record

Resource URL: https://servername/services/employeehire/v1/pendinghires

Sample from POST

{
    "Id": 0,
    "OfferId": "245",
    "RequisitionId": "N-714",
    "ImportDate": "2013-08-09T10:46:28.343",
    "EmployeeHireData": {
        "CompanyId": "C0014",
        "SsnOrSin": "222334444",
        "NamePrefixCode": "Ms",
        "NameFirst": "Diana",
        "NameMiddle": null,
        "NameLast": "Prince",
        "NameSuffixCode": null,
        "EmployeeNumber": null,
        "TimeclockId": null,
        "AddressLine1": "234 Oak Drive",
        "AddressLine2": null,
        "City": "1 Comic Lane",
        "StateOrProvinceCode": "DC",
        "ZipOrPostalCode": "23456",
        "HomePhoneNumber": "5555555555",
        "BusinessPhoneNumber": null,
        "BusinessPhoneExtension": null,
        "OtherPhoneNumber": null,
        "OtherPhoneTypeCode": null,
        "PrimaryEmailAddress": null,
        "AlternateEmailAddress": null,
        "DateOfBirth": null,
        "GenderCode": "F",
        "MaritalStatusCode": null,
        "EthnicCode": "1",
        "I9VerifiedCode": null,
        "StartDate": null,
        "JobGroupCode": null,
        "JobCode": "SUPPORT",
        "JobTitle": null,
        "LocationCode": "DC",
        "HireSourceCode": null,
        "OrgLevel1Code": null,
        "OrgLevel2Code": null,
        "OrgLevel3Code": null,
        "OrgLevel4Code": null,
        "PayRate": "85000",
        "RatePerCode": "Y",
        "PayGroupCode": null,
        "ScheduledWorkHours": null,
        "EarningsGroupCode": null,
        "DeductionBenefitGroupCode": null,
        "EmployeeTypeCode": null,
        "HourlyOrSalaryCode": "S",
        "FullTimeOrPartTimeCode": "P",
        "ShiftCode": null,
        "PositionCode": null
    },
    "SupplementalData": {
        "CandidateInfo": {
            "MilitaryEraCode": null,
            "MilitaryBranchServedCode": null,
           “IsDisabled”:”Y”,
           “IsVeteran”:”N”
        },
        "EducationInfo": [
            {
                "SchoolCode": "UNI",
  "FromDate": "2010-06-07",
  "ToDate": "2013-06-07",
  "Graduated": "True",
  "Years": 3,
  "MajorCode": "HUM",
  "MinorCode": "HR",
  "Location": "USA",
  "LevelCode": "M",
  "Gpa": "4.0",
                "Rank": "25",
                "Notes": null             
            }
      ],
        "ExperienceInfo": [ ],
        "LicenseInfo": [ ],
        "SkillInfo": [
            {
                "SkillCode": "ACT",
                "ProficiencyCode": "NOV",
                "AssesedOnDate": null,
                "AssessedBy": null,
                "Notes": null
            }
        ]
    }
}

Note - Supplemental Data is optional. It may be removed from the POST if not applicable.

Pending Hire Data - PUT with Record ID

The Pending Hire Data using PUT with Record ID is included in this section.

ParametersDescriptions
PUT with Record IDIndicates one unprocessed record to be updated.

Resource URL: https://servername/services/employeehire/v1/pendinghires(12)

Sample from PUT with Record ID

{
    "OfferId": "245",
    "RequisitionId": "N-714",
    "ImportDate": "2013-08-09T10:46:28.343",
    "EmployeeHireData": {
        "CompanyId": "C0014",
        "SsnOrSin": "222334444",
        "NamePrefixCode": "Ms",
        "NameFirst": "Diana",
        "NameMiddle": null,
        "NameLast": "Prince",
        "NameSuffixCode": null,
        "EmployeeNumber": null,
        "TimeclockId": null,
        "AddressLine1": "234 Oak Drive",
        "AddressLine2": null,
        "City": "1 Comic Lane",
        "StateOrProvinceCode": "DC",
        "ZipOrPostalCode": "23456",
        "HomePhoneNumber": "5555555555",
        "BusinessPhoneNumber": null,
        "BusinessPhoneExtension": null,
        "OtherPhoneNumber": null,
        "OtherPhoneTypeCode": null,
        "PrimaryEmailAddress": null,
        "AlternateEmailAddress": null,
        "DateOfBirth": null,
        "GenderCode": "F",
        "MaritalStatusCode": null,
        "EthnicCode": "1",
        "I9VerifiedCode": null,
        "StartDate": null,
        "JobGroupCode": null,
        "JobCode": "SUPPORT",
        "JobTitle": null,
        "LocationCode": "DC",
        "HireSourceCode": null,
        "OrgLevel1Code": null,
        "OrgLevel2Code": null,
        "OrgLevel3Code": null,
        "OrgLevel4Code": null,
        "PayRate": "86000", updated value
        "RatePerCode": "Y",
        "PayGroupCode": null,
        "ScheduledWorkHours": null,
        "EarningsGroupCode": null,
        "DeductionBenefitGroupCode": null,
        "EmployeeTypeCode": null,
        "HourlyOrSalaryCode": "S",
        "FullTimeOrPartTimeCode": "P",
        "ShiftCode": null,
        "PositionCode": null
    },
    "SupplementalData": {
        "CandidateInfo": {
            "MilitaryEraCode": null,
            "MilitaryBranchServedCode": null,
             “IsDisabled”:”Y”,
           “IsVeteran”:”N”


        },
        "EducationInfo": [
            {
                "SchoolCode": "UNI",
  "FromDate": "2010-06-07",
  "ToDate": "2013-06-07",
  "Graduated": "True",
  "Years": 3,
  "MajorCode": "HUM",
  "MinorCode": "HR",
  "Location": "USA",
  "LevelCode": "M",
  "Gpa": "4.0",
                "Rank": "25",
                "Notes": null             
            }
      ],
        "ExperienceInfo": [ ],
        "LicenseInfo": [ ],
        "SkillInfo": [
            {
                "SkillCode": "ACT",
                "ProficiencyCode": "NOV",
                "AssesedOnDate": null,
                "AssessedBy": null,
                "Notes": null
            }
        ]
    }
  }

Possible Return Values

The return codes with descriptive explanations for return values are included in the table.

Return CodeDescription
200 OKThe request has succeeded (for instance, on a GET).
201 CreatedThe POST was successful and a new record was created
204 No ContentThe PUT was successful and the record was updated.*
400 Bad RequestThe request was malformed, unable to be understood or contained validation errors.
401 UnauthorizedThe credentials proved were not able to be authenticated.
403 ForbiddenAccess to the requested resource is denied.
404 Not FoundThe Requested URI cannot be found.
500 Internal Server ErrorThe server encountered an unexpected condition which prevented it from fulfilling the request.
501 Not Implemented

The request is not supported.

Note: Delete is not supported on this API and will return this code.

* 204 No Content (return-no-content) is the default behavior. This can be changed to return the content of the successful PUT by altering the header (return-content). The syntax for the Prefer header is as follows:

Prefer = “Prefer" ":" preference

preference = "return-no-content" |

"return-content" |

preference-extension

preference-extension = prefer-params *( ";" prefer-params ])

prefer-params = token [ "=" ( token | quoted-string )