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 | |
---|---|
Protocol | HTTP (REST) |
SSL Support | Required |
Signup and Licensing | |
---|---|
Account Required | UKG 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.
Parameter | Description |
---|---|
GET | Returns 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.
Parameters | Description |
---|---|
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.
Parameter | Description |
---|---|
POST | Inserts 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.
Parameters | Descriptions |
---|---|
PUT with Record ID | Indicates 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 Code | Description |
---|---|
200 OK | The request has succeeded (for instance, on a GET). |
201 Created | The POST was successful and a new record was created |
204 No Content | The PUT was successful and the record was updated.* |
400 Bad Request | The request was malformed, unable to be understood or contained validation errors. |
401 Unauthorized | The credentials proved were not able to be authenticated. |
403 Forbidden | Access to the requested resource is denied. |
404 Not Found | The Requested URI cannot be found. |
500 Internal Server Error | The 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 )
Updated about 1 year ago