Employee New Hire Service


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

This document describes how to use the Employee New Hire Web service (for USA based employees) service and is intended for individuals who are familiar with software development and Web Services technologies.

UKG Pro Employee New Hire Service Application Programming Interface

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


This document describes the methods of the service and provides code examples using Microsoft’s Visual Studio 2010 using C# and XML (.NET Framework 3.0 or higher).

The following information describes the service requirements.

Service Specifications
ProtocolSimple Object Access Protocol (SOAP) 1.2
SSL SupportRequired
Signup and Licensing
Account RequiredUKG Pro 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 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. In this table, 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.
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
D=Debit Card
AmountRuleAmount rule
D=Flat Amount
P=Percent Amount
Default to available balance (A)
BankNameStringBank name
FlatOrPercentAmountRequired if AmountRule is Flat Amount or Percent AmountDecimalFlat or percent amount
Must be a positive decimal less or equal to 1 when amount rule is percent amount (P)
RoutingNumberOnly when direct deposit is providedIntRouting number
EarningsGroupYesCodeEarnings group code
EmailAddressStringPrimary Email address
EmployeeNumberStringEmployee number. If the company employee number method is set to SSN, Time clock number or automatic, this field will be ignored.
EmployeeTypeYesCodeEmployee type code
EthnicOriginCodeEthnic origin code
FederalAdditionalAmountWithheldMoneyAdditional amount withheld for Federal taxes.
FederalDeductionAmtNoMoneyDeductions from Step 4b of the Federal W-4
FederalDependentAmtNoMoneyClaim Dependents Total from Step 3 of the Federal W-4
FederalEmployeeClaimsExemptBooleanIf true, employee is exempt from Federal taxes.
FederalFilingStatusYesCodeFederal filing status code
FederalOtherIncomeNoMoneyOther Income from Step 4a of the Federal W-4
FederalSubjectToBackupWithholdingBooleanIf true, employee is subject to Federal backup tax withholding.
FederalTotalAllowancesClaimedIntTotal federal allowances claimed
FederalW2PensionBooleanIf true, enables the pension flag on the W2
FirstNameYesStringFirst name
FormerLastNameStringFormer last name

Employee status

F = Full time

P = Part time


Gender code.



HireDateYesDatetimeDate of hire
HireSourceCodeHire source code
HomePhoneStringHome phone number. Exclude dashes and parentheses.

Employee’s pay type

H = Hourly

S = Salaried

I9VerificationYesCodeI9 Verification code
JobCodeYesCodeJob code
JobGroupCodeJob group code
LastNameYesStringLast name

Determines whether the employee receives the local work in tax for being a resident or nonresident of the local municipality.

N = Non resident

R = Resident

LocationCodeYesCodeLocation code
MailStopStringMail stop
MaritalStatusCodeMarital Status code
MiddleNameStringMiddle name
NextPerformanceReviewDateDatetimeDate of next performance review
NextSalaryReviewDateDatetimeDate of next salary review
OrgLevel1CodeOrganizational 1 code
OrgLevel2CodeOrganizational 2 code
OrgLevel3CodeOrganizational 3 code
OrgLevel4CodeOrganizational 4 code
OtherPhoneStringOther Phone Number
OtherPhoneExtensionStringExtension for Other Phone Number
OtherPhoneTypeOnly when OtherPhone providedStringCode for the type of other phone number provided
OtherRate1MoneyRequires Master Company to be configured to use other rates
OtherRate2MoneyRequires Master Company to be configured to use other rates
OtherRate3MoneyRequires Master Company to be configured to use other rates
OtherRate4MoneyRequires Master Company to be configured to use other rates
PayAutomaticallyBooleanIf true, selects the employee to be auto paid
PayGroupYesCodePay group code
PayRateYesDecimalEmployee’s rate of pay. Set the PayRateType accordingly.

Type of pay rate entered in the PayRate.




Y=Yearly (Annual)

PreferredFirstNameStringPreferred first name
PrefixCodePrefix name code
ProjectCodeProject code
ResidentStateAdoptedDependentExemptionsNoNumericMust be greater than zero
ResidentStateDeductionAmtNoMoneyDeductions from Step 4b of the W-4 for state withholding. Ignored for states that do not use the Federal W-4 as their state withholding form
ResidentStateDependentAmountNoMoneyClaim Dependents Total from Step 3 of the W-4 for state withholding. Ignored for states that do not use the Federal W-4 as their state withholding form
ResidentOtherIncomeNoMoneyOther Income from Step 4a of the W-4 for state withholding. Ignored for states that do not use the Federal W-4 as their state withholding form
ResidentStateAdditionalAllowancesInt(4)Additional resident state allowances claimed. Ignored for states that do not have additional values.
ResidentStateAdditionalAmountWithheldMoneyAdditional amount withheld for resident state taxes.
ResidentStateEmployeeClaimsExemptBooleanIf true, employee is exempt from resident state taxes.
ResidentStateFilingStatusYesCodeResident state filing status code
ResidentStateTotalAllowancesClaimedIntTotal resident state allowances claimed.
ResidentStateTotalAllowancesClaimedCurrencyAmountOptional. Only to be used if the employee lives in Iowa and wants to specify Total Allowances Claimed for the corresponding location. Other states are not supported.Int10-digit maximum. Whole dollar amounts only. Decimals are not supported.
ScheduledHoursYesDecimalScheduled hours
SeniorityDateYesDatetimeDate of seniority
ShiftCodeCodeShift code
ShiftGroupCodeShift group code
SSNYesStringSocial Security Number
StateGeographicCodeCodeState geographic code. Only required for the state of Alaska.

Required for AK - Alaska

LA - Louisiana

Other states are not supported.

CodeState Occupational code.
StateOrProvinceYesCodeState or Province code.
SuffixCodeSuffix name code
SupervisorIdentifierID that represents a person that is the supervisor

Time clock code.

Required if the employee number method is set to time clock.

WorkStateAdoptedDependentExemptionsNoNumericMust be greater than zero.
WorkStateDeductionAmountNoMoneyDeductions from Step 4b of the W-4 for state withholding. Ignored for states that do not use the Federal W-4 as their state withholding form
WorkStateDependentAmountNoMoneyClaim Dependents Total from Step 3 of the W-4 for state withholding. Ignored for states that do not use the Federal W-4 as their state withholding form
WorkExtensionStringWork phone extension
WorkOtherIncomeNoMoneyOther Income from Step 4a of the W-4 for state withholding. Ignored for states that do not use the Federal W-4 as their state withholding form
WorkPhoneStringWork phone. Exclude dashes and parentheses.
WorkStateAdditionalAllowancesIntAdditional work state allowances claimed. Ignored for states that do not have additional values.
WorkStateAdditionalAmountWithheldMoneyAdditional amount withheld for work state taxes.
WorkStateDisabilityPlanTypeRequired for: CA, CO, CT, DC, MA, NJ, NY, OR, PR, WACode

State disability plan type code for the work state.

Required for states that have disability.

WorkStateEmployeeClaimsExemptBooleanIf true, employee is exempt from work state taxes.
WorkStateFilingStatusYesCodeWork state filing status code

State plan code.

Required for California.

WorkStateTotalAllowancesClaimedIntTotal work state allowances claimed.
WorkStateTotalAllowancesClaimedCurrencyAmountOptional. Only to be used if the employee works in Iowa and wants to specify Total Allowances Claimed for the corresponding location. Other states are not supported.Int10-digit maximum. Whole dollar amounts only. Decimals are not supported.
ZipOrPostalCodeYesStringZip / Postal code
DistributionCenterCodeCodeDistribution Center
ResidentCountyRequired for PA. Other states are currently not supportedStringResident county code
ResidentJurisdictionRequired for PA. Other states are currently not supportedStringResident Jurisdiction
PTOPlansCollection (Employee Accrual)Paid time off plan
AvailableDecimalCurrent PTO balance available
Defaults to: 0.0000
EarnedThroughDateDateEarned through date
Default to seniority date
PlanCodePTO plan code
Reset DateDateReset date
Based on plan's reset option:
If option is reset on a specific date, or on service anniversary, PTO Reset is defaulted to seniority date.
If option is never reset, PTO Reset is left blank.
PayScaleCodeStringRequired if UsePayScale=Y
StepNoRequired if UsePayScale=Y
UnionLocalCodeLocal Union code
UntionNationalCodeNational Union code

Quick Start

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


In order to use the service, you will need the following items:

  • An UKG Pro Service Account username and password (created on the System Configuration > Service Account Administration page) or a UKG Pro Web user account
  • The Customer API key from the UKG Pro Web Services page
  • If you use an UKG Pro Web 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 Employee New Hire service on the Service Account administrative page.
  • If you use an UKG Pro Web User account:
    • You will need the User API key from the Web Service administrative page.


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


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# Code 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 display 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.

Password = "YOUR PASSWORD",
namespace NewHireTest
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Channels;
    using NewHireTest.EmployeeNewHireService;
    using NewHireTest.LoginService;
        internalstaticvoid Main(string[] args)
            // Setup your user credentials:
            conststring UserName = "";
            conststring Password = "";
            conststring CustomerApiKey = "";
            conststring UserApiKey = "";
            // Create a proxy to the login service:
            var loginClient = newLoginServiceClient("WSHttpBinding_ILoginService");
                // Submit the login request to authenticate the user:
                string message;
                string authenticationToken;
                AuthenticationStatus loginRequest =
                            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);
                    // User authentication has failed. Review the message for details.
                    Console.WriteLine("User authentication failed: " + message);
                Console.WriteLine("Press a key to exit...");
            catch (Exception ex)
                Console.WriteLine("Exception: " + ex);
        privatestaticvoid HireEmployee(string customerApi, string token)
            conststring ultiproTokenNamespace =
            conststring ClientAccessKeyNamespace =
            // Create a proxy to the employee new hire service:
            var employeeNewHireClient = newEmployeeNewHireClient("WSHttpBinding_IEmployeeNewHire");
                // Add the headers for the customer API key and authentication token:
                using (newOperationContextScope(employeeNewHireClient.InnerChannel))
                        MessageHeader.CreateHeader("ultiproToken", ultiproTokenNamespace, token));
                        MessageHeader.CreateHeader("ClientAccessKey", ClientAccessKeyNamespace, customerApi));
                    // Create an employee and set the values:
                    var employee =
                            AddressLine1 = "123 Main St",
                            AddressLine2 = String.Empty,
                           AlternateEmailAddress = String.Empty,
                            AlternateTitle = "Sales Rep",
                            BenefitSeniorityDate = newDateTime(2016, 4, 1),
                            BirthDate = newDateTime(1970, 1, 1),
                            City = "Sydney",
                            CompanyIdentifier =
                                    CompanyCode = "PRU"
                            Country = "USA",
                            County = String.Empty,
                            DeductionBenefitGroup = "SAL",
                            DistributionCenterCode = String.Empty,
                           DirectDeposits = new[]{
                                    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 = newDateTime(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 = newDateTime(2012, 10, 1),
                            NextSalaryReviewDate = newDateTime(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[]
                                     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 = newDateTime(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 =
                                    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
                            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);
                        Console.WriteLine("New hire success.");
            catch (Exception ex)
                Console.WriteLine("Exception: " + ex);

XML Example

Authentication Service (http://<address>/services/LoginService)
The Authentication Service 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.


    <a:Actions:mustUnderstand="1">http://www.ultimatesoftware.com/services/employeenewhire/IEmployeeNewHire/NewHireUsa       </a:Action>
    <ultiproTokenxmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">d91e98fe-560a-4e30-b00e-85117a3629c1 </ultiproToken>
          <b:AddressLine1>123 Maple Ln.</b:AddressLine1>
              <b:BankName>Wells Fargo</b:BankName>