Employee New Hire Service

UKG Pro Web Services API Guide

Employee New Hire Service

Introduction

With UKG’s UKG Pro Web Services, you can leverage your UKG Pro data for solving business application and integration needs.

This document is intended for individuals who are familiar with software development and web service technologies.

Employee New Hire Service API

The UKG Pro Employee New Hire Service Application Programming Interface (API) enables the user to programmatically hire an employee into a UKG Pro company based in the United States.

This document describes the methods of the service and provides examples for how to use the Employee New Hire web service for USA-based employees.

Service Specifications

  • Protocol: Simple Object Access Protocol (SOAP) 1.2
  • SSL Support: Required

Signup and Licensing

  • Account Required: One of the following is required:
    • UKG Pro Web User with Web Services permissions
    • UKG Pro Service Account

Using a UKG Pro Service Account is recommended. For information regarding establishing and maintaining a UKG Pro Service Account, refer to the Manage Service Accounts guide located in the UKG Pro Learning Center (Home > Content > System Management > Web Services).

Employee New Hire Object

The Employee New Hire object includes the following properties. Some of the data is grouped as a data collection. The fields within each data collection should be used together.

For example:

  • The DirectDeposits section is a collection of DirectDeposit elements.
  • The PTOPlans section is a collection of EmployeeAccrual elements.
PropertyRequiredTypeDescription
AddressLine1YesStringAddress line 1
AddressLine2StringAddress line 2
AlternateEmailAddressStringAlternate email address
AlternateTitleStringAlternate job title
BenefitSeniorityDateYesDatetimeBenefit seniority date
BirthDateYesDatetimeBirth date
CityYesStringAddress city
CompanyIdentifierYesIdentifierIdentifier that represents a UKG Pro component company. Select Company Code, Federal ID, or Import code and provide the value.
CountryYesCodeCurrently, only USA is supported with this service. Use the Global or Canadian new hire service for other countries.
CountyStringAddress county
DeductionBenefitGroupYesCodeDeduction / Benefit group code
Direct DepositsCollectionDirect Deposit records
AccountIsActiveBooleanAccount status. Default to 'True'
AccountNumberOnly when direct deposit is providedStringAccount number
AccountTypeYesCodeAccount type:
  • C = Checking
  • D = Debit Card
  • S = Savings |
    | AmountRule | | | Amount rule:
  • D = Flat Amount
  • P = Percent Amount
  • A = Available Balance
    Default to available balance ('A') |
    | BankName | | String | Bank name |
    | FlatOrPercentAmount | Required if AmountRule is Flat Amount or Percent Amount | Decimal | Flat or percent amount. Must be a positive decimal less than or equal to 1 when the amount rule is percent amount ('P'). |
    | RoutingNumber | Only when direct deposit is provided | Int | Routing number |

(Additional table rows continue in the same format...)

Quick Start

This section provides steps for creating a sample application in your development environment to hire an employee in a USA-based company.

Prerequisites

To use the service, you will need the following items:

  • A UKG Pro Service Account username and password or a UKG Pro Web User username and password
  • The Customer API key from the UKG Pro Web Service administrative page
    • If you use a UKG Pro Service Account:
      • You will need the User API key from the Service Account administrative page.
      • You must have appropriate permissions granted to the Service Account for the Development Opportunity service on the Service Account administrative page.
    • If you use a UKG Pro Web User account, you will need the User API key from the Web Service administrative page.

Methods

This section introduces the API methods for the Employee New Hire Web Service.

NewHireUsa

This method provides a way to hire an employee to a US-based company in UKG Pro. You must provide the minimum required fields listed in the new hire object in order to successfully hire an employee.

C# Example

Generate the Service Reference

Once you have a user and API keys, you need to create a service reference to the Login Service and the New Hire Service. In your development environment, add the service references.

In Visual Studio, select the Add Service Reference menu item from the Project menu. Once you enter the service information, you should have the references displayed in the solution explorer.

Created service reference
Created service reference

Example Code

The following code is an example of adding a new employee in a console application. Copy the entire contents to a C# console application and update the following values to build an operable application.

UserName = "YOUR SERVICE ACCOUNT OR WEB USER NAME ",
Password = "YOUR PASSWORD",
UserAPIkey = "YOUR USER API KEY",
CustomerAPIkey = "YOUR CUSTOMER API KEY"

namespace NewHireTest
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Channels;
 
    using NewHireTest.EmployeeNewHireService;
    using NewHireTest.LoginService;
 
    public class Program
    {
        internal static void Main(string[] args)
        {
            // Setup your user credentials:
            const string UserName = "";
            const string Password = "";
            const string CustomerApiKey = "";
            const string UserApiKey = "";
 
            // Create a proxy to the login service:
            var loginClient = new LoginServiceClient("WSHttpBinding_ILoginService");
 
            try
            {
                // Submit the login request to authenticate the user:
                string message;
                string authenticationToken;
                AuthenticationStatus loginRequest =
                    loginClient
                        .Authenticate(
                            CustomerApiKey,
                            Password,
                            UserApiKey,
                            UserName,
                            out message,
                            out authenticationToken);
 
                if (loginRequest == AuthenticationStatus.Ok)
                {
                    // User is authenticated and the authentication token is provided.
                    Console.WriteLine("User authentication successful.");
 
                    // Hire employee:
                    HireEmployee(CustomerApiKey, authenticationToken);
                }
                else
                {
                    // User authentication has failed. Review the message for details.
                    Console.WriteLine("User authentication failed: " + message);
                }
 
                loginClient.Close();
 
                Console.WriteLine("Press a key to exit...");
                Console.ReadKey(true);
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception: " + ex);
                loginClient.Abort();
                throw;
            }
        }
 
        private static void HireEmployee(string customerApi, string token)
        {
            const string UltiProTokenNamespace =
                "http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken";
 
            const string ClientAccessKeyNamespace =
                "http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey";
 
            // Create a proxy to the employee new hire service:
            var employeeNewHireClient = new EmployeeNewHireClient("WSHttpBinding_IEmployeeNewHire");
 
            try
            {
                // Add the headers for the customer API key and authentication token:
                using (new OperationContextScope(employeeNewHireClient.InnerChannel))
                {
                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader("UltiProToken", UltiProTokenNamespace, token));
 
                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader("ClientAccessKey", ClientAccessKeyNamespace, customerApi));
 
                    // Create an employee and set the values:
                    var employee =
                        new Employee
                        {
                            AddressLine1 = "123 Main St",
                            AddressLine2 = String.Empty,
                            AlternateEmailAddress = String.Empty,
                            AlternateTitle = "Sales Rep",
                            BenefitSeniorityDate = new DateTime(2016, 4, 1),
                            BirthDate = new DateTime(1970, 1, 1),
                            City = "Sydney",
                            CompanyIdentifier =
                                new CompanyCodeIdentifier
                                {
                                    CompanyCode = "PRU"
                                },
                            Country = "USA",
                            County = String.Empty,
                            DeductionBenefitGroup = "SAL",
                            DistributionCenterCode = String.Empty,
                            DirectDeposits = new[]{
                                new DirectDeposit
                                {
                                    AccountIsActive = true,
                                    AccountNumber = "854954546",
                                    AccountType = "C", 
                                    AmountRule = "P",
                                    BankName = "Wells Fargo",
                                    FlatOrPercentAmount = Decimal.Parse("0.50"),
                                    RoutingNumber = "122100024"
                                }
                            },
                            EarningsGroup = "SAL",
                            EmailAddress = "[email protected]",
                            EmployeeNumber = "689479",
                            EmployeeType = "REG",
                            EthnicOrigin = "1",
                            FederalAdditionalAmountWithheld = 0,
                            FederalEmployeeClaimsExempt = false,
                            FederalFilingStatus = "M",
                            FederalSubjectToBackupWithholding = false,
                            FederalTotalAllowancesClaimed = 1,
                            FederalW2Pension = false,
                            FirstName = "Jacob",
                            FormerLastName = String.Empty,
                            FullOrPartTime = "F",
                            Gender = "M",
                            HireDate = new DateTime(2012, 4, 1),
                            HireSource = "EEREF",
                            HomePhone = "7405551212",
                            HourlyOrSalaried = "S",
                            I9Verification = "P",
                            JobCode = "SALES",
                            JobGroup = "WEBSA",
                            LastName = "Smith",
                            LocalWorkInTaxResidentStatus = "R",
                            LocationCode = "OH",
                            MailStop = String.Empty,
                            MaritalStatus = "M",
                            MiddleName = "R",
                            NextPerformanceReviewDate = new DateTime(2012, 10, 1),
                            NextSalaryReviewDate = new DateTime(2012, 10, 1),
                            OtherPhone = String.Empty,
                            OtherPhoneExtension = String.Empty,
                            OtherPhoneType = String.Empty,
                            OtherRate1 = 1.5m,
                            OtherRate2 = null,
                            OtherRate3 = null,
                            OtherRate4 = null,
                            OrgLevel1 = "SE",
                            OrgLevel2 = String.Empty,
                            OrgLevel3 = String.Empty,
                            OrgLevel4 = String.Empty,
                            PayAutomatically = false,
                            PayGroup = "UPC",
                            PayRate = 30500.00m,
                            PayRateType = "Y",
                            PayScaleCode = null,
                            PreferredFirstName = "Jay",
                            Prefix = String.Empty,
                            Project = String.Empty,
                            PTOPlans = new[]
                            {
                                new EmployeeAccrual
                                {
                                    Available = Decimal.Zero,
                                    EarnedThroughDate = DateTime.Now.AddDays(100),
                                    Plan = "IKANOR",
                                    ResetDate = DateTime.Now.AddDays(100)
                                }
                            },
                            ResidentCounty = null,
                            ResidentJurisdiction = null,
                            ResidentStateAdditionalAllowances = 0,
                            ResidentStateAdditionalAmountWithheld = 0,
                            ResidentStateEmployeeClaimsExempt = false,
                            ResidentStateFilingStatus = "M",
                            ResidentStateTotalAllowancesClaimed = 0,
                            ScheduledHours = 40m,
                            SeniorityDate = new DateTime(2012, 4, 1),
                            ShiftCode = String.Empty,
                            ShiftGroup = String.Empty,
                            SSN = "299001934",
                            StateGeographicCode = String.Empty,
                            StateOccupationalCode = String.Empty,
                            StateOrProvince = "OH",
                            StepNo = null,
                            Suffix = String.Empty,
                            Supervisor =
                                new EmployeeNumberIdentifier
                                {
                                    EmployeeNumber = "046546546"
                                },
                            TimeClock = String.Empty,
                            UnionLocal = String.Empty,
                            UnionNational = String.Empty,
                            WorkExtension = "289",
                            WorkPhone = "9543317000",
                            WorkStateAdditionalAllowances = 0,
                            WorkStateAdditionalAmountWithheld = 0,
                            WorkStateDisabilityPlanType = String.Empty,
                            WorkStateEmployeeClaimsExempt = false,
                            WorkStateFilingStatus = "M",
                            WorkStatePlan = String.Empty,
                            WorkStateTotalAllowancesClaimed = 1,
                            ZipOrPostalCode = "43135"
                        };
 
                    // Hire the employee:
                    CreateResponse createResponse =
                        employeeNewHireClient.NewHireUsa(new[] { employee });
 
                    // Check the results of the hire to see if there are any errors:
                    if (createResponse.OperationResult.HasErrors)
                    {
                        // Review each error:
                        foreach (OperationMessage message in
                            createResponse.OperationResult.Messages)
                        {
                            Console.WriteLine("Error message: " + message.Message);
                        }
                    }
 
                    // Check the response results for any errors:
                    if (createResponse.HasErrors)
                    {
                        foreach (Result result in createResponse.Results)
                        {
                            Console.WriteLine("HasErrors: {0}", result.HasErrors);
                            Console.WriteLine("HasWarnings: {0}", result.HasWarnings);
                            Console.WriteLine("Success: {0}", result.Success);
 
                            foreach (var message in result.Messages)
                            {
                                Console.WriteLine("\tCode: {0}", message.Code);
                                Console.WriteLine("\tMessage: {0}", message.Message);
                                Console.WriteLine("\tPropertyName: {0}", message.PropertyName);
                                Console.WriteLine("\tSeverity: {0}\n", message.Severity);
                            }
                        }
                    }
                    else
                    {
                        Console.WriteLine("New hire success.");
                    }
                }
 
                employeeNewHireClient.Close();
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception: " + ex);
                employeeNewHireClient.Abort();
            }
        }
    }
}

This formatted block represents the C# code for hiring a new employee using UKG's services.

XML Example

The Authentication Service (http://

/services/LoginService) is required to get the Token needed for all Core Web Service Calls. Please refer to the UKG Pro Login Service API Guide for further information.

NewHire

s:Envelopexmlns:s="http://www.w3.org/2003/05/soap-envelope"xmlns:a="http://www.w3.org/2005/08/addressing"
<s:Header>
<a:Actions:mustUnderstand="1">http://www.ultipro.com/services/employeenewhire/IEmployeeNewHire/NewHireUsa </a:Action>
UltiProTokenxmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken"d91e98fe-560a-4e30-b00e-85117a3629c1
ClientAccessKeyxmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey"
0QMDG

<a:MessageID>urn:uuid:3d6bc06c-b4c1-4469-ba70-0909e80da211</a:MessageID>
<a:ReplyTo>
<a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
</a:ReplyTo>
<a:Tos:mustUnderstand="1">http://tuna4hx/services/EmployeeNewHire</a:To>
</s:Header>
<s:Body>
NewHireUsaxmlns="http://www.ultipro.com/services/employeenewhire"
entitiesxmlns:b="http://www.ultipro.com/contracts"xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
<b:Employee>
<b:AddressLine1>123 Maple Ln.</b:AddressLine1>
<b:AddressLine2/>
<b:AlternateEmailAddress/>
<b:AlternateTitle/>
<b:BenefitSeniorityDate>2015-09-16T00:00:00</b:BenefitSeniorityDate>
<b:BirthDate>2001-01-01T00:00:00</b:BirthDate>
<b:City>Piermont</b:City>
<b:CompanyIdentifieri:type="b:CompanyCodeIdentifier">
<b:CompanyCode>C0013</b:CompanyCode>
</b:CompanyIdentifier>
<b:Country>USA</b:Country>
<b:County/>
<b:DeductionBenefitGroup>AUTO</b:DeductionBenefitGroup>
<b:DirectDeposits>
<b:DirectDeposit>
<b:AccountIsActive>1</b:AccountIsActive>
<b:AccountNumber>999999999</b:AccountNumber>
<b:AccountType>C</b:AccountType>
<b:AmountRule>P</b:AmountRule>
<b:BankName>Wells Fargo</b:BankName>
<b:FlatOrPercentAmount>0.50</b:FlatOrPercentAmount>
<b:RoutingNumber>122100024</b:RoutingNumber>
</b:DirectDeposit>
</b:DirectDeposits>
<b:DistributionCenterCode/>
<b:EarningsGroup>EXEC</b:EarningsGroup>
<b:EmailAddress/>
<b:EmployeeNumber>asdfar343</b:EmployeeNumber>
<b:EmployeeType>reg</b:EmployeeType>
<b:EthnicOrigin>1</b:EthnicOrigin>
<b:FederalAdditionalAmountWithheld>0</b:FederalAdditionalAmountWithheld>
<b:FederalEmployeeClaimsExempt>false</b:FederalEmployeeClaimsExempt>
<b:FederalFilingStatus>m</b:FederalFilingStatus>
<b:FederalSubjectToBackupWithholding>false</b:FederalSubjectToBackupWithholding>
<b:FederalTotalAllowancesClaimed>0</b:FederalTotalAllowancesClaimed>
<b:FederalW2Pension>false</b:FederalW2Pension>
<b:FirstName>Joe</b:FirstName>
<b:FormerLastName/>
<b:FullOrPartTime>f</b:FullOrPartTime>
<b:Gender>f</b:Gender>
<b:HireDate>2015-09-15T00:00:00</b:HireDate>
<b:HireSource/>
<b:HomePhone/>
<b:HourlyOrSalaried>h</b:HourlyOrSalaried>
<b:I9Verification/>
<b:JobCode>ACCTG</b:JobCode>
<b:JobGroup/>
<b:LastName>Tester</b:LastName>
<b:LocalWorkInTaxResidentStatus/>
<b:LocationCode>FL</b:LocationCode>
<b:MailStop/>
<b:MaritalStatus/>
<b:MiddleName/>
<b:NextPerformanceReviewDate>0001-01-01T00:00:00</b:NextPerformanceReviewDate>
<b:NextSalaryReviewDate>0001-01-01T00:00:00</b:NextSalaryReviewDate>
<b:OrgLevel1/>
<b:OrgLevel2/>
<b:OrgLevel3/>
<b:OrgLevel4/>
<b:OtherPhone/>
<b:OtherPhoneExtension/>
<b:OtherPhoneType/>
<b:OtherRate1i:nil="true"/>
<b:OtherRate2i:nil="true"/>
<b:OtherRate3i:nil="true"/>
<b:OtherRate4i:nil="true"/>
<b:PTOPlans>
<b:EmployeeAccrual>
<b:Available>0.0000</b:Available>
<b:EarnedThroughDate>2020-05-05T12:00:00</b:EarnedThroughDate>
<b:Plan>IKANOR</b:Plan>
<b:ResetDate>2020-05-05T12:00:00</b:ResetDate>
</b:EmployeeAccrual>
</b:PTOPlans>
<b:PayAutomatically>false</b:PayAutomatically>
<b:PayGroup>WEBPRB</b:PayGroup>
<b:PayRate>0</b:PayRate>
<b:PayRateType>H</b:PayRateType>
<b:PayScaleCode/>
<b:PreferredFirstName/>
<b:Prefix/>
<b:Project/>
<b:ResidentCounty/>
<b:ResidentJurisdiction/>
<b:ResidentStateAdditionalAllowances>0</b:ResidentStateAdditionalAllowances>
<b:ResidentStateAdditionalAmountWithheld>0</b:ResidentStateAdditionalAmountWithheld>
<b:ResidentStateEmployeeClaimsExempt>false</b:ResidentStateEmployeeClaimsExempt>
<b:ResidentStateFilingStatus>M</b:ResidentStateFilingStatus>
<b:ResidentStateTotalAllowancesClaimed>0</b:ResidentStateTotalAllowancesClaimed>
<b:ResidentStateTotalAllowancesClaimedCurrencyAmount>0
</b:ResidentStateTotalAllowancesClaimedCurrencyAmount>
<b:SSN>123458771</b:SSN>
<b:ScheduledHours>0</b:ScheduledHours>
b:SelfServicePropertiesxmlns:c="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
<c:KeyValueOfstringstring>
<c:Key/>
<c:Value/>
</c:KeyValueOfstringstring>
</b:SelfServiceProperties>
<b:SeniorityDate>2015-09-16T00:00:00</b:SeniorityDate>
<b:ShiftCode/>
<b:ShiftGroup/>
<b:StateGeographicCode/>
<b:StateOccupationalCode>11-2021</b:StateOccupationalCode>
<b:StateOrProvince>LA</b:StateOrProvince>
<b:StepNoi:nil="true"/>
<b:Suffix/>
<b:Supervisori:type="b:SsnIdentifier">
<b:CompanyCode>C0013</b:CompanyCode>
<b:Ssn>373299087</b:Ssn>
</b:Supervisor>
<b:TimeClock/>
<b:UnionLocal/>
<b:UnionNational/>
<b:WorkExtension/>
<b:WorkPhone/>
<b:WorkStateAdditionalAllowances>0</b:WorkStateAdditionalAllowances>
<b:WorkStateAdditionalAmountWithheld>0</b:WorkStateAdditionalAmountWithheld>
<b:WorkStateDisabilityPlanType/>
<b:WorkStateEmployeeClaimsExempt>false</b:WorkStateEmployeeClaimsExempt>
<b:WorkStateFilingStatus>M</b:WorkStateFilingStatus>
<b:WorkStatePlan/>
<b:WorkStateTotalAllowancesClaimed>0</b:WorkStateTotalAllowancesClaimed>
<b:WorkStateTotalAllowancesClaimedCurrencyAmount>0
</b:WorkStateTotalAllowancesClaimedCurrencyAmount>
<b:ZipOrPostalCode>33172</b:ZipOrPostalCode>
</b:Employee>


</s:Body>
</s:Envelope>