UKG Pro Web Services API Guide

For example:

• The DirectDeposits section is a collection of DirectDeposit elements.
• The PTOPlans section is a collection of EmployeeAccrual elements.

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.

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.

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;
 
    publicclassProgram
    {
        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");
 
            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;
            }
        }
 
        privatestaticvoid HireEmployee(string customerApi, string token)
        {
            conststring UltiProTokenNamespace =
                "http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken";
 
            conststring ClientAccessKeyNamespace =
                "http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey";
 
            // Create a proxy to the employee new hire service:
            var employeeNewHireClient = newEmployeeNewHireClient("WSHttpBinding_IEmployeeNewHire");
 
            try
            {
                // Add the headers for the customer API key and authentication token:
                using (newOperationContextScope(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 =
                        newEmployee
                        {
                            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 =
                                newCompanyCodeIdentifier
                                {
                                    CompanyCode = "PRU"
                              },
                            Country = "USA",
                            County = String.Empty,
                            DeductionBenefitGroup = "SAL",
                            DistributionCenterCode = String.Empty,
                           DirectDeposits = new[]{
                                
                                newDirectDeposit
                                {
                                    AccountIsActive = true,
                                    AccountNumber = "854954546",
                                    AccountType = "C", 
                                    AmountRule = "P",
                                    BankName = "Wells Fargo",
                                    FlatOrPercentAmount = Decimal.Parse("0.50"),
                                    RoutingNumber = "122100024"
                                }
 
 
                                },
                            EarningsGroup = "SAL",
                            EmailAddress = "jsmith@ausco.com",
                            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[]
                            {
                              
                                 newEmployeeAccrual
                                 {
                                     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 =
                                newEmployeeNumberIdentifier
                                {
                                    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();
            }
        }
    }
}

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 </UltiProToken>
    <ClientAccessKeyxmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">
      0QMDG
    </ClientAccessKey>
    <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>
      </entities>
    </NewHireUsa>
  </s:Body>
</s:Envelope>