Canadian New Hire Service

UKG Pro Web Services API Guide

UKG Pro Canadian 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.

Overview

This document describes the methods of the service and provides code examples using Microsoft’s Visual Studio 2010 using C#.

The following information describes the service requirements.

Service SpecificationsDetails
ProtocolSimple Object Access Protocol (SOAP) 1.2
SSL SupportRequired
Signup and LicensingDetails
Account RequiredUKG Pro Web User or UKG Pro Site Admin with API keys

Employee Canadian New Hire Object

The employee Canadian new hire object includes the following properties.

PropertyRequiredTypeDescription
AboriginalPersonStringY=Yes, N=No, Blank = Decline to answer
AddressLine1YesStringAddress line 1
AddressLine2StringAddress line 2
AlternateEmailAddressStringAlternate email address
AlternateTitleStringAlternate job title
BenefitSeniorityDateYesDateBenefit seniority date
BirthDateYesDateBirth date
CityYesStringAddress city
CompanyIdentifierYesReferenceIdentifier that represents an UKG Pro component company. Select Company Code, Federal ID or Import code and provide the value.
CountryYesCode listAddress country code
DeductionBenefitGroupYesCode listDeduction / Benefit group code
EarningsGroupYesCode listEarnings 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.
EmployeeTypeYesCode listEmployee type code
EthnicityCode listEthnic origin code
FederalContributionMonthsIntEnter values of 1-11 if you wish to prorate the contribution to the pension plan.
FederalEmploymentInsuranceExemptBooleanIf true, employee is exempt from federal employment insurance.
FederalIncomeExemptBooleanIf true, the employee is exempt from federal income tax. Personal tax credit information will be ignored if this is true.
FederalPensionPlanExemptBooleanIf true, the employee is exempt from the Canada Pension Plan. This can only be true if the FederalWithholdPensionPlan is false.
FederalWithholdPensionPlanBooleanIf true, the Canada Pension Plan will be withheld and reported.
FirstNameYesStringFirst name
FormerLastNameStringFormer last name
FullOrPartTimeYesCode listEmployee status
GenderYesCode listGender code. M=Male, F=Female
HireDateYesDateDate of hire
HireSourceCode listHire source code
HomePhoneStringHome phone number. Exclude dashes and parentheses.
HourlyOrSalariedYesCode listEmployee’s pay type
JobCodeYesCode listJob code
JobGroupCode listJob group code
LastNameYesStringLast name
LocalUnionCode listLocal union code
LocationCodeYesCode listLocation code
MailStopStringMail stop
MaritalStatusCode listMarital Status code
MiddleNameStringMiddle name
NationalUnionCode listNational union code
NextPerformanceReviewDateDateDate of next performance review
NextSalaryReviewDateDateDate of next salary review
OrgLevel1Code listOrganizational 1 code
OrgLevel2Code listOrganizational 2 code
OrgLevel3Code listOrganizational 3 code
OrgLevel4Code listOrganizational 4 code
PayAutomaticallyBooleanIf true, selects the employee to be auto paid
PayGroupYesCode listPay group code
PayRateYesDecimalEmployee’s rate of pay. Set the PayRateType accordingly.
PayRateTypeYesCode listType of pay rate entered in the PayRate. H=Hourly, P=Period, W=Weekly, Y=Yearly (Annual)
PayStatementLanguageYesCode listPreferred language for the employee’s pay statement. EN = English, FR = French
PersonalAdditionalTaxDecimalAdditional personal tax to be deducted
PersonalAnnualDeductionToIncomeDecimalAdditional annual deduction to income when employee requests a reduction in tax deductions.
PersonalCommissionedEmployeeBooleanIf true, employee is commissioned claiming expenses.
PersonalEstimatedCommissionExpenseDecimalIf a commissioned employee, the estimated amount of commission expense.
PersonalEstimatedRemunerationDecimalIf a commissioned employee, the estimated total remuneration.
PersonalEstimatedYearlyDeductionAmountDecimalIf a commissioned employee, the estimated total deduction amount for the year.
PersonalIncomeLessthanTotalClaimBooleanIf true, the total income is less than total claim amount. If true, all other personal tax credit properties are ignored.
PersonalOtherFederalCreditsDecimalOther federal tax credits when employee requests a reduction in tax deductions.
PersonalPrescribedZoneAmountDecimalDeduction amount for living in a prescribed zone.
PersonalTotalClaimAmountDecimalTotal claim amount if any when not using the basic personal amount.
PersonalUseBasicAmountBooleanIf true, the basic personal amount will be used for the person tax credits. If true, PersonalTotalClaimAmount and PersonalIncomeLessthanTotalClaim will be ignored.
PreferredFirstNameStringPreferred first name
PrefixCode listPrefix name code
ProjectCode listProject code
ProvincialAdditionalTaxDecimalAdditional personal provincial tax to be deducted
ProvincialAnnualDeductionToIncomeDecimalAdditional annual deduction to income when employee requests a reduction in tax deductions.
ProvincialIncomeExemptBooleanIf true, the employee is exempt from provincial income tax. Provincial personal tax credits will be ignored if true.
ProvincialIncomeLessthanTotalClaimBooleanIf true, the total income is less than total claim amount. If true, all other personal tax credit properties are ignored.
ProvincialNumberofDependentsIntNumber of dependents. Valid for the provinces of Manitoba and Ontario.
ProvincialOtherTaxCreditsDecimalOther provincial tax credits when employee requests a reduction in tax deductions.
ProvincialPrescribedZoneAmountDecimalDeduction amount for living in a prescribed zone and/or deductible support payments.
ProvincialTotalClaimAmountDecimalTotal claim amount if any when not using the basic personal amount.
ProvincialUseBasicAmountBooleanIf true, the basic personal amount will be used for the person tax credits. If true, ProvincialTotalClaimAmount and ProvincialIncomeLessthanTotalClaim will be ignored.
QuebecContributionMonthsIntEnter values of 1-11 if you wish to prorate the contribution to the Quebec pension plan.
QuebecParentalInsuranceExemptBooleanIf true, the employee is exempt from the Parental Insurance Plan when the work location province is Quebec.
QuebecPensionPlanExemptBooleanIf true, the employee is exempt from the Quebec pension plan when the work location province is Quebec.
QuebecWithholdPensionPlanBooleanIf true, the Quebec Pension Plan will be withheld and reported. If true, the QuebecPensionPlanExempt must be false.
ScheduledHoursYesDecimalScheduled hours
SeniorityDateYesDateDate of seniority
ShiftCodeCode listShift code
ShiftGroupCode listShift group code
SINYesStringSocial Insurance Number
SSNStringSocial Security Number
StateOrProvinceYesCode listState or Province code
SuffixCode listSuffix name code
SupervisorReferenceID that represents a person that is the supervisor
TimeClockStringTime clock code. Required if the employee number method is set to time clock.
VisibleMinorityMemberStringIs the employee a member of a visible minority? Y=Yes, N=No, Blank = Decline to answer
WorkExtensionStringWork phone extension
WorkPhoneStringWork phone. Exclude dashes and parenthesis.
ZipOrPostalCodeYesStringZip / Postal Code

Quick Start

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

Prerequisites

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

  • UKG Pro Web user account and password
  • User API key and Customer API key from the UKG Pro Web service administrative page

Methods

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

NewHireCanada

This method provides a way to hire an employee to a Canadian-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.

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 Canadian 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

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 WEB USER NAME ";
Password = "YOUR PASSWORD";
UserAPIkey = "YOUR USER API KEY";
CustomerAPIkey = "YOUR CUSTOMER API KEY";

// Example Quick Start Code Begin

using System;
using System.Collections.Generic;
using System.Linq;
using System.ServiceModel;
using System.ServiceModel.Channels;
using System.Text;
using EmployeeCanadianNewHire.LoginService;
using EmployeeCanadianNewHire.NewHireCanadianService;

namespace EmployeeCanadianNewHire
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                // Setup your user credentials.
                string UserName = "";
                string Password = "";
                string UserAPIkey = "";
                string CustomerAPIkey = "";
                string Message = "";
                string AuthenticationToken = "";

                // Create a proxy to the login service.
                LoginServiceClient loginClient = new LoginServiceClient("WSHttpBinding_ILoginService");

                // Submit the login request to authenticate the user.
                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 an employee
                    NewHire(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.Message.ToString());
            }
        }

        static void NewHire(string CustomerAPI, string Token)
        {
            try
            {
                // Create a proxy to the new hire service.
                EmployeeCanadianNewHireClient proxyHire = new EmployeeCanadianNewHireClient("WSHttpBinding_IEmployeeCanadianNewHire");

                // Add the headers for the Customer API key and authentication token.
                using (new System.ServiceModel.OperationContextScope(proxyHire.InnerChannel))
                {
                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader("UltiProToken",
                        "http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken", Token));
                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader("ClientAccessKey",
                        "http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey",
                        CustomerAPI));

                    // Create an employee and set the values.
                    var newHire = new CanadianEmployee
                    {
                        AboriginalPerson = "N",
                        AddressLine1 = "123 Main St",
                        AddressLine2 = string.Empty,
                        AlternateEmailAddress = string.Empty,
                        AlternateTitle = "Sales Rep",
                        BenefitSeniorityDate = new DateTime(2012, 4, 1),
                        BirthDate = new DateTime(1970, 1, 1),
                        City = "Toronto",
                        CompanyIdentifier = new CompanyCodeIdentifier { CompanyCode = "CW1" },
                        Country = "CAN",
                        DeductionBenefitGroup = "CALL",
                        EarningsGroup = "CALL",
                        EmailAddress = "[email protected]",
                        EmployeeNumber = "68947",
                        EmployeeType = "REG",
                        Ethnicity = "1",
                        FederalEmploymentInsuranceExempt = false,
                        FederalIncomeExempt = false,
                        FederalPensionPlanExempt = false,
                        FederalWithholdPensionPlan = true,
                        FirstName = "Jacob",
                        FormerLastName = string.Empty,
                        FullOrPartTime = "F",
                        Gender = "M",
                        HireDate = new DateTime(2012, 4, 1),
                        HireSource = string.Empty,
                        HomePhone = "4168611100",
                        HourlyOrSalaried = "S",
                        JobCode = "CANJOB4",
                        JobGroup = "",
                        LastName = "Smith",
                        LocalUnion = string.Empty,
                        LocationCode = "TORONT",
                        MailStop = string.Empty,
                        MaritalStatus = "M",
                        MiddleName = "R",
                        NationalUnion = string.Empty,
                        NextPerformanceReviewDate = new DateTime(2012, 10, 1),
                        NextSalaryReviewDate = new DateTime(2012, 10, 1),
                        OrgLevel1 = "CANR01",
                        OrgLevel2 = "CAN005",
                        OrgLevel3 = string.Empty,
                        OrgLevel4 = string.Empty,
                        PayAutomatically = false,
                        PayGroup = "CANWEB",
                        PayRate = 50000.00m,
                        PayRateType = "Y",
                        PayStatementLanguage = "EN",
                        PersonalUseBasicAmount = true,
                        PreferredFirstName = "Jay",
                        ProvincialIncomeExempt = false,
                        ProvincialNumberofDependents = 2,
                        ProvincialUseBasicAmount = true,
                        ScheduledHours = 80m,
                        SeniorityDate = new DateTime(2012, 4, 1),
                        ShiftCode = string.Empty,
                        ShiftGroup = string.Empty,
                        SIN = "162637201",
                        SSN = string.Empty,
                        StateOrProvince = "ON",
                        Suffix = string.Empty,
                        Supervisor = new EmployeeNumberIdentifier { EmployeeNumber = "555655159" },
                        TimeClock = string.Empty,
                        VisibleMinorityMember = "N",
                        WorkExtension = "289",
                        WorkPhone = "4168611200",
                        ZipOrPostalCode = "M5H3L5"
                    };

                    // Add the new hire.
                    CreateResponse createResponse = proxyHire.NewHireCanada(new[] { newHire });

                    // Check the operational results for 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 (var result in createResponse.Results)
                        {
                            Console.WriteLine("HasErrors: " + result.HasErrors);
                            Console.WriteLine("HasWarnings: " + result.HasWarnings);
                            Console.WriteLine("Success: " + result.Success);

                            foreach (var message in result.Messages)
                            {
                                Console.WriteLine("\tCode: " + message.Code);
                                Console.WriteLine("\tMessage: " + message.Message);
                                Console.WriteLine("\tPropertyName: " + message.PropertyName);
                                Console.WriteLine("\tSeverity: " + message.Severity + "\n");
                            }
                        }
                    }
                    else
                    {
                        Console.WriteLine("New hire success.");
                    }
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception: " + ex.Message.ToString());
            }
        }
    }
}

// Example Quick Start Code End

XML Examples

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.

New Hire Canada

<s:Envelope xmlns:a="http://www.w3.org/2005/08/addressing" xmlns:s="http://www.w3.org/2003/05/soap-envelope">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://www.ultipro.com/services/employeecanadiannewhire/IEmployeeCanadianNewHire/NewHireCanada</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">2cc9adb0-2eb3-4132-bce5-d47f9ec2bd02</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <NewHireCanada xmlns="http://www.ultipro.com/services/employeecanadiannewhire">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:CanadianEmployee>
          <b:AboriginalPerson i:nil="true" /> 
          <b:AddressLine1>123 Maple</b:AddressLine1> 
          <b:AddressLine2 i:nil="true" /> 
          <b:AlternateEmailAddress i:nil="true" /> 
          <b:AlternateTitle i:nil="true" /> 
          <b:BenefitSeniorityDate>2013-04-13T00:00:00</b:BenefitSeniorityDate> 
          <b:BirthDate>1980-01-01T00:00:00</b:BirthDate> 
          <b:City>Toronto</b:City> 
          <b:CompanyIdentifier i:type="b:CompanyCodeIdentifier">
            <b:CompanyCode>CW1</b:CompanyCode> 
          </b:CompanyIdentifier>
          <b:Country>CAN</b:Country> 
          <b:DeductionBenefitGroup>CALL</b:DeductionBenefitGroup> 
          <b:EarningsGroup>CALL</b:EarningsGroup> 
          <b:EmailAddress i:nil="true" /> 
          <b:EmployeeNumber>2468</b:EmployeeNumber> 
          <b:EmployeeType>REG</b:EmployeeType> 
          <b:Ethnicity i:nil="true" /> 
          <b:FederalContributionMonths>0</b:FederalContributionMonths> 
          <b:FederalEmploymentInsuranceExempt>false</b:FederalEmploymentInsuranceExempt> 
          <b:FederalIncomeExempt>false</b:FederalIncomeExempt> 
          <b:FederalPensionPlanExempt>false</b:FederalPensionPlanExempt> 
          <b:FederalWithholdPensionPlan>false</b:FederalWithholdPensionPlan> 
          <b:FirstName>John</b:FirstName> 
          <b:FormerLastName i:nil="true" /> 
          <b:FullOrPartTime>F</b:FullOrPartTime> 
          <b:Gender>M</b:Gender> 
          <b:HireDate>2013-04-13T00:00:00</b:HireDate> 
          <b:HireSource i:nil="true" /> 
          <b:HomePhone>5554449999</b:HomePhone> 
          <b:HourlyOrSalaried>S</b:HourlyOrSalaried> 
          <b:JobCode>CANJOB4</b:JobCode> 
          <b:JobGroup i:nil="true" /> 
          <b:LastName>Tester</b:LastName> 
          <b:LocalUnion i:nil="true" /> 
          <b:LocationCode>TORONT</b:LocationCode> 
          <b:MailStop i:nil="true" /> 
          <b:MaritalStatus i:nil="true" /> 
          <b:MiddleName>D</b:MiddleName> 
          <b:NationalUnion i:nil="true" /> 
          <b:NextPerformanceReviewDate>2014-04-13T00:00:00</b:NextPerformanceReviewDate> 
          <b:NextSalaryReviewDate>2014-04-13T00:00:00</b:NextSalaryReviewDate> 
          <b:OrgLevel1 i:nil="true" /> 
          <b:OrgLevel2 i:nil="true" /> 
          <b:OrgLevel3 i:nil="true" /> 
          <b:OrgLevel4 i:nil="true" /> 
          <b:PayAutomatically>false</b:PayAutomatically> 
          <b:PayGroup>CANWEB</b:PayGroup> 
          <b:PayRate>500000</b:PayRate> 
          <b:PayRateType>Y</b:PayRateType> 
          <b:PayStatementLanguage>EN</b:PayStatementLanguage> 
          <b:PersonalAdditionalTax>0</b:PersonalAdditionalTax> 
          <b:PersonalAnnualDeductionToIncome>0</b:PersonalAnnualDeductionToIncome> 
          <b:PersonalCommissionedEmployee>false</b:PersonalCommissionedEmployee> 
          <b:PersonalEstimatedCommissionExpense>0</b:PersonalEstimatedCommissionExpense> 
          <b:PersonalEstimatedRemuneration>0</b:PersonalEstimatedRemuneration> 
          <b:PersonalEstimatedYearlyDeductionAmount>0</b:PersonalEstimatedYearlyDeductionAmount> 
          <b:PersonalIncomeLessthanTotalClaim>false</b:PersonalIncomeLessthanTotalClaim> 
          <b:PersonalOtherFederalCredits>0</b:PersonalOtherFederalCredits> 
          <b:PersonalPrescribedZoneAmount>0</b:PersonalPrescribedZoneAmount> 
          <b:PersonalTotalClaimAmount>0</b:PersonalTotalClaimAmount> 
          <b:PersonalUseBasicAmount>false</b:PersonalUseBasicAmount> 
          <b:PreferredFirstName>John</b:PreferredFirstName> 
          <b:Prefix i:nil="true" /> 
          <b:Project i:nil="true" /> 
          <b:ProvincialAdditionalTax>0</b:ProvincialAdditionalTax> 
          <b:ProvincialAnnualDeductionToIncome>0</b:ProvincialAnnualDeductionToIncome> 
          <b:ProvincialIncomeExempt>false</b:ProvincialIncomeExempt> 
          <b:ProvincialIncomeLessthanTotalClaim>false</b:ProvincialIncomeLessthanTotalClaim> 
          <b:ProvincialNumberofDependents>0</b:ProvincialNumberofDependents> 
          <b:ProvincialOtherTaxCredits>0</b:ProvincialOtherTaxCredits> 
          <b:ProvincialPrescribedZoneAmount>0</b:ProvincialPrescribedZoneAmount> 
          <b:ProvincialTotalClaimAmount>0</b:ProvincialTotalClaimAmount> 
          <b:ProvincialUseBasicAmount>false</b:ProvincialUseBasicAmount> 
          <b:QuebecContributionMonths>0</b:QuebecContributionMonths> 
          <b:QuebecParentalInsuranceExempt>false</b:QuebecParentalInsuranceExempt> 
          <b:QuebecPensionPlanExempt>false</b:QuebecPensionPlanExempt> 
          <b:QuebecWithholdPensionPlan>false</b:QuebecWithholdPensionPlan> 
          <b:SIN i:nil="true" /> 
          <b:SINExpiryDate>0001-01-01T00:00:00</b:SINExpiryDate> 
          <b:SSN i:nil="true" /> 
          <b:ScheduledHours>80</b:ScheduledHours> 
          <b:SelfServiceProperties xmlns:c="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
            <c:KeyValueOfstringstring>
              <c:Key /> 
              <c:Value /> 
            </c:KeyValueOfstringstring>
          </b:SelfServiceProperties>
          <b:SeniorityDate>2013-04-13T00:00:00</b:SeniorityDate> 
          <b:ShiftCode i:nil="true" /> 
          <b:ShiftGroup i:nil="true" /> 
          <b:StateOrProvince>ON</b:StateOrProvince> 
          <b:Suffix i:nil="true" /> 
          <b:Supervisor i:nil="true" /> 
          <b:TimeClock i:nil="true" /> 
          <b:VisibleMinorityMember i:nil="true" /> 
          <b:WorkExtension i:nil="true" /> 
          <b:WorkPhone>5558884444</b:WorkPhone> 
          <b:ZipOrPostalCode>M5H3L5</b:ZipOrPostalCode> 
        </b:CanadianEmployee>
      </entities>
    </NewHireCanada>
  </s:Body>
</s:Envelope>