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 Specifications | Details |
---|---|
Protocol | Simple Object Access Protocol (SOAP) 1.2 |
SSL Support | Required |
Signup and Licensing | Details |
---|---|
Account Required | UKG 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.
Property | Required | Type | Description |
---|---|---|---|
AboriginalPerson | String | Y=Yes, N=No, Blank = Decline to answer | |
AddressLine1 | Yes | String | Address line 1 |
AddressLine2 | String | Address line 2 | |
AlternateEmailAddress | String | Alternate email address | |
AlternateTitle | String | Alternate job title | |
BenefitSeniorityDate | Yes | Date | Benefit seniority date |
BirthDate | Yes | Date | Birth date |
City | Yes | String | Address city |
CompanyIdentifier | Yes | Reference | Identifier that represents an UKG Pro component company. Select Company Code, Federal ID or Import code and provide the value. |
Country | Yes | Code list | Address country code |
DeductionBenefitGroup | Yes | Code list | Deduction / Benefit group code |
EarningsGroup | Yes | Code list | Earnings group code |
EmailAddress | String | Primary Email address | |
EmployeeNumber | String | Employee number. If the company employee number method is set to SSN, Time clock number or automatic, this field will be ignored. | |
EmployeeType | Yes | Code list | Employee type code |
Ethnicity | Code list | Ethnic origin code | |
FederalContributionMonths | Int | Enter values of 1-11 if you wish to prorate the contribution to the pension plan. | |
FederalEmploymentInsuranceExempt | Boolean | If true, employee is exempt from federal employment insurance. | |
FederalIncomeExempt | Boolean | If true, the employee is exempt from federal income tax. Personal tax credit information will be ignored if this is true. | |
FederalPensionPlanExempt | Boolean | If true, the employee is exempt from the Canada Pension Plan. This can only be true if the FederalWithholdPensionPlan is false. | |
FederalWithholdPensionPlan | Boolean | If true, the Canada Pension Plan will be withheld and reported. | |
FirstName | Yes | String | First name |
FormerLastName | String | Former last name | |
FullOrPartTime | Yes | Code list | Employee status |
Gender | Yes | Code list | Gender code. M=Male, F=Female |
HireDate | Yes | Date | Date of hire |
HireSource | Code list | Hire source code | |
HomePhone | String | Home phone number. Exclude dashes and parentheses. | |
HourlyOrSalaried | Yes | Code list | Employee’s pay type |
JobCode | Yes | Code list | Job code |
JobGroup | Code list | Job group code | |
LastName | Yes | String | Last name |
LocalUnion | Code list | Local union code | |
LocationCode | Yes | Code list | Location code |
MailStop | String | Mail stop | |
MaritalStatus | Code list | Marital Status code | |
MiddleName | String | Middle name | |
NationalUnion | Code list | National union code | |
NextPerformanceReviewDate | Date | Date of next performance review | |
NextSalaryReviewDate | Date | Date of next salary review | |
OrgLevel1 | Code list | Organizational 1 code | |
OrgLevel2 | Code list | Organizational 2 code | |
OrgLevel3 | Code list | Organizational 3 code | |
OrgLevel4 | Code list | Organizational 4 code | |
PayAutomatically | Boolean | If true, selects the employee to be auto paid | |
PayGroup | Yes | Code list | Pay group code |
PayRate | Yes | Decimal | Employee’s rate of pay. Set the PayRateType accordingly. |
PayRateType | Yes | Code list | Type of pay rate entered in the PayRate. H=Hourly, P=Period, W=Weekly, Y=Yearly (Annual) |
PayStatementLanguage | Yes | Code list | Preferred language for the employee’s pay statement. EN = English, FR = French |
PersonalAdditionalTax | Decimal | Additional personal tax to be deducted | |
PersonalAnnualDeductionToIncome | Decimal | Additional annual deduction to income when employee requests a reduction in tax deductions. | |
PersonalCommissionedEmployee | Boolean | If true, employee is commissioned claiming expenses. | |
PersonalEstimatedCommissionExpense | Decimal | If a commissioned employee, the estimated amount of commission expense. | |
PersonalEstimatedRemuneration | Decimal | If a commissioned employee, the estimated total remuneration. | |
PersonalEstimatedYearlyDeductionAmount | Decimal | If a commissioned employee, the estimated total deduction amount for the year. | |
PersonalIncomeLessthanTotalClaim | Boolean | If true, the total income is less than total claim amount. If true, all other personal tax credit properties are ignored. | |
PersonalOtherFederalCredits | Decimal | Other federal tax credits when employee requests a reduction in tax deductions. | |
PersonalPrescribedZoneAmount | Decimal | Deduction amount for living in a prescribed zone. | |
PersonalTotalClaimAmount | Decimal | Total claim amount if any when not using the basic personal amount. | |
PersonalUseBasicAmount | Boolean | If true, the basic personal amount will be used for the person tax credits. If true, PersonalTotalClaimAmount and PersonalIncomeLessthanTotalClaim will be ignored. | |
PreferredFirstName | String | Preferred first name | |
Prefix | Code list | Prefix name code | |
Project | Code list | Project code | |
ProvincialAdditionalTax | Decimal | Additional personal provincial tax to be deducted | |
ProvincialAnnualDeductionToIncome | Decimal | Additional annual deduction to income when employee requests a reduction in tax deductions. | |
ProvincialIncomeExempt | Boolean | If true, the employee is exempt from provincial income tax. Provincial personal tax credits will be ignored if true. | |
ProvincialIncomeLessthanTotalClaim | Boolean | If true, the total income is less than total claim amount. If true, all other personal tax credit properties are ignored. | |
ProvincialNumberofDependents | Int | Number of dependents. Valid for the provinces of Manitoba and Ontario. | |
ProvincialOtherTaxCredits | Decimal | Other provincial tax credits when employee requests a reduction in tax deductions. | |
ProvincialPrescribedZoneAmount | Decimal | Deduction amount for living in a prescribed zone and/or deductible support payments. | |
ProvincialTotalClaimAmount | Decimal | Total claim amount if any when not using the basic personal amount. | |
ProvincialUseBasicAmount | Boolean | If true, the basic personal amount will be used for the person tax credits. If true, ProvincialTotalClaimAmount and ProvincialIncomeLessthanTotalClaim will be ignored. | |
QuebecContributionMonths | Int | Enter values of 1-11 if you wish to prorate the contribution to the Quebec pension plan. | |
QuebecParentalInsuranceExempt | Boolean | If true, the employee is exempt from the Parental Insurance Plan when the work location province is Quebec. | |
QuebecPensionPlanExempt | Boolean | If true, the employee is exempt from the Quebec pension plan when the work location province is Quebec. | |
QuebecWithholdPensionPlan | Boolean | If true, the Quebec Pension Plan will be withheld and reported. If true, the QuebecPensionPlanExempt must be false. | |
ScheduledHours | Yes | Decimal | Scheduled hours |
SeniorityDate | Yes | Date | Date of seniority |
ShiftCode | Code list | Shift code | |
ShiftGroup | Code list | Shift group code | |
SIN | Yes | String | Social Insurance Number |
SSN | String | Social Security Number | |
StateOrProvince | Yes | Code list | State or Province code |
Suffix | Code list | Suffix name code | |
Supervisor | Reference | ID that represents a person that is the supervisor | |
TimeClock | String | Time clock code. Required if the employee number method is set to time clock. | |
VisibleMinorityMember | String | Is the employee a member of a visible minority? Y=Yes, N=No, Blank = Decline to answer | |
WorkExtension | String | Work phone extension | |
WorkPhone | String | Work phone. Exclude dashes and parenthesis. | |
ZipOrPostalCode | Yes | String | Zip / 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
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>
Updated 2 months ago