UKG Pro Web Services API Guide

Employee Contacts 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 Contacts Service API

The UKG Pro Employee Contacts Service API enables the user to programmatically retrieve and update employee contact information in UKG Pro.

Overview

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

The following information describes the service requirements.

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 Contacts Object

The employee contacts object includes the following properties:

Property	Required	Type	Description
ActiveContact		Boolean	If true, sets the contact as active.
Address		String	Defaults to the employee address unless AddressIsDifferent is set to true.
Address2		String	Defaults to the employee address2 unless AddressIsDifferent is set to true.
AddressIsDifferent		Boolean	If the address is different from the employees, set this to true and you can enter all other address information.
Beneficiary		Boolean	If true, enables the contact as a beneficiary.
City		String	Defaults to the employee city unless AddressIsDifferent is set to true.
ContactId		String	A unique id to identify an existing contact.
Country		Code	A valid country code. Defaults to the employee country unless AddressIsDifferent is set to true.
County		String	Defaults to the employee county unless AddressIsDifferent is set to true.
DateOfBirth		Datetime	Contacts date of birth.
DateOfDivorce		Datetime	Contacts date of divorce.
DateOfMarriage		Datetime	Contacts date of marriage.
DeceasedDate		Datetime	Contacts deceased date.
Dependent		Boolean	If true, enables the contact as a dependent.
Disabled		Boolean
EmergencyContact		Boolean	If true, enables the contact as an emergency contact.
EmployeeIdentifier	Yes	Identifier	ID that represents a person that this contact is related to.
Employer		String	Contacts employer.
FirstName	Yes	String	Contacts first name.
FormerLastName		String	Contacts former last name.
FullTimeStudent		Boolean	If true, enables the contact as a full time student.
Gender		Code	M = Male F = Female
HomePhone		String	Required if preferred phone is set to home.
LastName	Yes	String	Contacts last name.
MiddleName		String	Contacts middle name.
NationalID		String	Contacts national id. An example would be a Canadian contacts’ Social Insurance Number.
NationalIDExpirationDate		Datetime	National Id expiration date.
Notes		String
Occupation		String	Contacts occupation.
OtherInsurance		Boolean	If true, enables the contact as covered by other insurance.
OtherPhone		String	Required if preferred phone is set to other. Additional phone for the given OtherPhoneType code.
OtherPhoneType		Code	Enter a valid UKG Pro other telephone type.
PreferredPhone	Yes	Code	The preferred phone for the contact. H = Home O = Other W = Work
RelationShipCode	Yes	Code	Enter a valid relationship code
SSN		String	Contacts Social Security Number.
Smoker		Boolean	If true, enables the contact as a smoker.
StateOrProvince		Code	Enter a valid UKG Pro state or province code. Defaults to the employee state unless AddressIsDifferent is set to true.
SuffixCode		Code	Enter a valid UKG Pro suffix code.
WorkExtension		String	Contacts work extension.
WorkPhone		String	Required if preferred phone is set to work.
ZipOrPostalCode		String	Enter a zip or postal code for the provided state or province. Defaults to the employee zip code unless AddressIsDifferent is set to true.

Quick Start

This section provides steps for creating a sample application in your development environment to retrieve and update the employee contact information.

Prerequisites

In order 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 Employee Contacts 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 Contacts Web Service.

FindContacts

This method provides a way to query the web service based on one or more filter criteria. See the getting started guide for a list of query properties and operations supported.

Note that the paging properties may be set when using this method. You can specify the PageNumber and PageSize. The page number indicates which page you want to return and the PageSize refers to the number of records to return per PageNumber. You can return a maximum of 100 records per PageNumber.

CreateContact

This method allows you to insert contacts for an employee.

GetContactByEmployeeIdentifier

This method allows you to retrieve contacts for an employee by providing an employee identifier. This is helpful if you are designing an application that is aware of the employees to retrieve or when you plan to execute an update of the contact information.

GetEmployeeContactByContactId

This method allows you to retrieve a contact for an employee by providing the unique contact id. This is helpful if you are designing an application that is aware of the employees to retrieve or when you plan to execute an update of the contact information.

UpdateContact

This method allows you to update the contact information. We recommend executing a find or get to retrieve the contact information first then submitting the object to the update method.

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 Contacts 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 see the references displayed in the solution explorer.

Created service reference
Created service reference

Example C# Code

The following code is an example of retrieving employee contact information from your UKG Pro data in a console application. You can copy the entire contents to a C# console application and update the following values and have an operable application.

See the methods section for an example of adding inserts and updates to your application.

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

Example Quick Start Code

using System;
using System.Collections.Generic;
using System.Linq;
using System.ServiceModel;
using System.ServiceModel.Channels;
using System.Text;
using ConsoleContacts.ContactsService;
using ConsoleContacts.LoginService;

namespace ConsoleContacts
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a proxy to the login service.
            LoginServiceClient loginClient = new LoginServiceClient("WSHttpBinding_ILoginService");
            
            try
            {
                // Setup your user credentials.
                string UserName = "YOUR SERVICE ACCOUNT OR WEB USER NAME";
                string Password = "YOUR PASSWORD";
                string UserAPIkey = "YOUR USER API KEY";
                string CustomerAPIkey = "YOUR CUSTOMER API KEY";
                string Message = "";
                string AuthenticationToken = "";

                // 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.");

                    // Find contacts
                    FindContacts(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();
            }
        }

        static void FindContacts(string CustomerAPI, string Token)
        {
            // Create a proxy to the contacts service.
            EmployeeContactsClient proxyContacts = new EmployeeContactsClient("WSHttpBinding_IEmployeeContacts");

            try
            {
                // Add the headers for the Customer API key and authentication token.
                using (new OperationContextScope(proxyContacts.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 a query object to find the employees.
                    EmployeeQuery query = new EmployeeQuery();

                    // Set one or more properties to search.
                    query.LastName = "LIKE (arco%)";
                    query.FullOrPartTime = "=F";

                    // Set paging properties  
                    query.PageSize = 10;
                    query.PageNumber = 1;

                    // Search for the employees and contacts.
                    ContactFindResponse response = proxyContacts.FindContacts(query);

                    // Check the results of the find to see if there are any errors.
                    if (response.OperationResult.HasErrors)
                    {
                        // Review each error.
                        foreach (OperationMessage message in response.OperationResult.Messages)
                        {
                            Console.WriteLine("Error message: " + message.Message);
                        }
                    }
                    else
                    {
                        // If employee records are returned, loop through the results and write out the data.
                        Array employeecontacts = response.Results;

                        foreach (EmployeeContact employeecontact in employeecontacts)
                        {
                            foreach (Contact contact in employeecontact.Contacts)
                            {
                                Console.WriteLine("Contact name: " + contact.LastName + ", " + contact.FirstName);
                            }
                        }

                        var pagingInfo = response.OperationResult.PagingInfo;
                        
                        Console.WriteLine("The employee query returned a total of " + pagingInfo.TotalItems + " records.");
                        Console.WriteLine("The employee query returned a total of " + pagingInfo.PageTotal + " pages.");
                        Console.WriteLine("Each page contains " + pagingInfo.PageSize + " records.");
                        Console.WriteLine("The Results contain the records for page " + pagingInfo.CurrentPage + ".");
                    }
                }

                proxyContacts.Close();
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception: " + ex);
                proxyContacts.Abort();
            }
        }
    }
}

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.

FindContacts

<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/employeecontacts/IEmployeeContacts/FindContacts</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">03959e43-b52e-4bd9-914f-b22139997e35</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <FindContacts xmlns="http://www.ultipro.com/services/employeecontacts">
      <query xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:CompanyCode /> 
        <b:CompanyName /> 
        <b:Country /> 
        <b:EmployeeNumber /> 
        <b:FirstName>like (a%)</b:FirstName> 
        <b:FormerName /> 
        <b:FullOrPartTime /> 
        <b:Job /> 
        <b:LastHire /> 
        <b:LastName /> 
        <b:Location /> 
        <b:OrganizationLevel1 /> 
        <b:OrganizationLevel2 /> 
        <b:OrganizationLevel3 /> 
        <b:OrganizationLevel4 /> 
        <b:OriginalHire /> 
        <b:PageNumber /> 
        <b:PageSize /> 
        <b:PayGroup /> 
        <b:Status /> 
        <b:SupervisorLastName /> 
        <b:TerminationDate /> 
        <b:TimeClockId /> 
      </query>
    </FindContacts>
  </s:Body>
</s:Envelope>

GetContactByEmployeeIdentifier

<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/employeecontacts/IEmployeeContacts/GetContactByEmployeeIdentifier</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">03959e43-b52e-4bd9-914f-b22139997e35</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <GetContactByEmployeeIdentifier xmlns="http://www.ultipro.com/services/employeecontacts">
      <employeeIdentifier xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" i:type="b:EmployeeNumberIdentifier">
        <b:CompanyCode>C0014</b:CompanyCode> 
        <b:EmployeeNumber>555667788</b:EmployeeNumber> 
      </employeeIdentifier>
    </GetContactByEmployeeIdentifier>
  </s:Body>
</s:Envelope>

GetEmployeeContactbyContactId

<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/employeecontacts/IEmployeeContacts/GetEmployeeContactByContactId</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">03959e43-b52e-4bd9-914f-b22139997e35</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <GetEmployeeContactByContactId xmlns="http://www.ultipro.com/services/employeecontacts">
      <contactId>9JE4AM0000K0</contactId> 
    </GetEmployeeContactByContactId>
  </s:Body>
</s:Envelope>

CreateContact

<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/employeecontacts/IEmployeeContacts/CreateContact</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">03959e43-b52e-4bd9-914f-b22139997e35</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <CreateContact xmlns="http://www.ultipro.com/services/employeecontacts">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:Contact>
          <b:ActiveContact>true</b:ActiveContact> 
          <b:Address i:nil="true" /> 
          <b:Address2 i:nil="true" /> 
          <b:AddressIsDifferent>false</b:AddressIsDifferent> 
          <b:Beneficiary>false</b:Beneficiary> 
          <b:City i:nil="true" /> 
          <b:ContactId i:nil="true" /> 
          <b:Country i:nil="true" /> 
          <b:County i:nil="true" /> 
          <b:DateOfBirth>0001-01-01T00:00:00</b:DateOfBirth> 
          <b:DateOfDivorce>0001-01-01T00:00:00</b:DateOfDivorce> 
          <b:DateOfMarriage>0001-01-01T00:00:00</b:DateOfMarriage> 
          <b:DeceasedDate>0001-01-01T00:00:00</b:DeceasedDate> 
          <b:Dependent>true</b:Dependent> 
          <b:Disabled>false</b:Disabled> 
          <b:EmailAddress i:nil="true" /> 
          <b:EmergencyContact>false</b:EmergencyContact> 
          <b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
            <b:CompanyCode>C0014</b:CompanyCode> 
            <b:EmployeeNumber>555667788</b:EmployeeNumber> 
          </b:EmployeeIdentifier>
          <b:Employer i:nil="true" /> 
          <b:FirstName>Jimmy</b:FirstName> 
          <b:FormerLastName i:nil="true" /> 
          <b:FullTimeStudent>false</b:FullTimeStudent> 
          <b:Gender /> 
          <b:HomePhone>5557779999</b:HomePhone> 
          <b:LastName>Doe</b:LastName> 
          <b:MiddleName i:nil="true" /> 
          <b:NationalID i:nil="true" /> 
          <b:NationalIDExpirationDate>0001-01-01T00:00:00</b:NationalIDExpirationDate> 
          <b:Notes i:nil="true" /> 
          <b:Occupation i:nil="true" /> 
          <b:OtherInsurance>false</b:OtherInsurance> 
          <b:OtherPhone i:nil="true" /> 
          <b:OtherPhoneType i:nil="true" /> 
          <b:PreferredPhone i:nil="true" /> 
          <b:RelationShipCode i:nil="true" /> 
          <b:SSN i:nil="true" /> 
          <b:Smoker>false</b:Smoker> 
          <b:StateOrProvince i:nil="true" /> 
          <b:SuffixCode i:nil="true" /> 
          <b:WorkExtension i:nil="true" /> 
          <b:WorkPhone i:nil="true" /> 
          <b:ZipOrPostalCode i:nil="true" /> 
        </b:Contact>
      </entities>
    </CreateContact>
  </s:Body>
</s:Envelope>

UpdateContact

<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/employeecontacts/IEmployeeContacts/UpdateContact</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">03959e43-b52e-4bd9-914f-b22139997e35</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <UpdateContact xmlns="http://www.ultipro.com/services/employeecontacts">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:Contact>
          <b:ActiveContact>true</b:ActiveContact> 
          <b:Address /> 
          <b:Address2 /> 
          <b:AddressIsDifferent>false</b:AddressIsDifferent> 
          <b:Beneficiary>false</b:Beneficiary> 
          <b:City /> 
          <b:ContactId>9JE4JF0000K0</b:ContactId> 
          <b:Country /> 
          <b:County /> 
          <b:DateOfBirth>0001-01-01T00:00:00</b:DateOfBirth> 
          <b:DateOfDivorce>0001-01-01T00:00:00</b:DateOfDivorce> 
          <b:DateOfMarriage>0001-01-01T00:00:00</b:DateOfMarriage> 
          <b:DeceasedDate>0001-01-01T00:00:00</b:DeceasedDate> 
          <b:Dependent>true</b:Dependent> 
          <b:Disabled>false</b:Disabled> 
          <b:EmailAddress /> 
          <b:EmergencyContact>false</b:EmergencyContact> 
          <b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
            <b:CompanyCode>C0014</b:CompanyCode> 
            <b:EmployeeNumber>555667788</b:EmployeeNumber> 
          </b:EmployeeIdentifier>
          <b:Employer /> 
          <b:FirstName>James</b:FirstName> 
          <b:FormerLastName /> 
          <b:FullTimeStudent>false</b:FullTimeStudent> 
          <b:Gender /> 
          <b:HomePhone>5557779999</b:HomePhone> 
          <b:LastName>Doe</b:LastName> 
          <b:MiddleName /> 
          <b:NationalID /> 
          <b:NationalIDExpirationDate>0001-01-01T00:00:00</b:NationalIDExpirationDate> 
          <b:Notes /> 
          <b:Occupation /> 
          <b:OtherInsurance>false</b:OtherInsurance> 
          <b:OtherPhone /> 
          <b:OtherPhoneType /> 
          <b:PreferredPhone /> 
          <b:RelationShipCode /> 
          <b:SSN /> 
          <b:Smoker>false</b:Smoker> 
          <b:StateOrProvince /> 
          <b:SuffixCode /> 
          <b:WorkExtension /> 
          <b:WorkPhone /> 
          <b:ZipOrPostalCode /> 
        </b:Contact>
      </entities>
    </UpdateContact>
  </s:Body>
</s:Envelope>