Introduction

Third-Party Pay Service API

The Third-Party Pay Service API enables you to import payroll summary information into UKG Pro so that your employees can view their pay summary within UKG Pro although the payroll was not processed in UKG Pro.

Overview

This document describes the methods of the service and provides examples.

The following information describes the service requirements.


Service Specifications
Protocol	HTTP (REST)
SSL Support	Required


Signup and Licensing
Account Required	UKG Pro Web Service Account

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).

Third-Party Pay Data

The following information describes the service data.

Table 1. External Pay Header
Property	Required	Min Length	Max Length	Notes
AddressLine1	NO	1	255
AddressLine2	NO	1	255
AddressMunicipality	NO	1	255
AddressRegion	NO	1	255
CheckAddModeCode	NO	1	1
CheckNumber	NO	-	-
CompanyIdentifierType & Value	NO	5	5	If provided, must be a valid Company Identifier Type: Company Code CompanyId FederalId ImportCode
CountryCode	NO	3	3	Must be a valid ISO Country Code
DateTimeChanged	NO	N/A	N/A	Read Only
DateTimeCreated	NO	N/A	N/A	Read Only
DocumentNumber	NO	1	25
EmployeeIdentifierType & Value	YES	1	12	Must be a valid Employee Identifier Type: EmployeeId EmployeeNumber EmployeeNumber Ssn EmailAddress Sin NationalId PersonId
EmployeeNumber	NO	1	25
Id	YES	N/A	N/A	GET: Exposed POST: Auto generated by the service, but exposed on response PUT: Client provides Id for resource updating (within URL), exposed on response DELETE: Client provides Id for resource updating (within URL)
IsVoided	NO	1	1	Y or N value not case sensitive. Defaults to N.
JobCode	NO	1	100
LocationDescription	NO	1	25
NameFirst	NO	1	100
NameLast	NO	1	100
OrgLevel1	NO	1	50
OrgLevel2	NO	1	50
OrgLevel3	NO	1	50
OrgLevel4	NO	1	50
CheckAmount	NO	-	-	Allows negative amounts
CurrentNetPay	NO	-	-	Allows negative amounts
CurrencyCode	YES	3	3	Must be a valid 3 character currency code
TotalCurrentDeductions	NO	-	-	Allows negative amounts
TotalCurrentEarnings	NO	-	-	Allows negative amounts
TotalCurrentTaxes	NO	-	-	Allows negative amounts
TotalYtdDeductions	NO	-	-	Allows negative amounts
TotalYtdEarnings	NO	-	-	Allows negative amounts
TotalYtdNetPay	NO	-	-	Allows negative amounts
TotalYtdTaxes	NO	-	-	Allows negative amounts
PayCompanyId	NO	5	5	If provided, must be a valid Company Identifier Type: Company Code CompanyId FederalId ImportCode
PayDate	YES	19	23	Formatting must conform to ISO8601. Example: 2014-04-01T11:21:20.069673-04:00
PayGroupCode	NO	1	6
PayrollCountryCode	YES	3	3	Must be a valid ISO Country Code
PeriodControl	NO	9	9
PeriodEndDate	NO	19	23	Formatting must conform to ISO860. Example: 2014-04-01T11:21:20.069673-04:00
PeriodStartDate	NO	19	23	Formatting must conform to ISO8601. Example: 2014-04-01T11:21:20.069673-04:00
PostalCode	NO	1	50
SourceSystem	NO	-	10	Defaults to an empty string
SystemId	NO	1	36	Can be used to store the unique Id of system that data originated from

Table 2. External Pay Earnings
Property	Required	Min Length	Max Length	Notes
EarningCode	NO	1	25	If only earning code is provided, code displays on Third-Party Pay page
EarningDescription	NO	1	50	If only earning description is provided, description displays on Third-Party Pay page If earning code and description are provided, description displays If neither earning code or description is provided, will display blank
EarningHours	NO	-	-
ExcludeInTotalHours	NO	1	1	Y or N value not case sensitive
ThirdPartyPayId	YES	N/A	N/A	GET: Exposed POST: Auto generated by the service, but exposed on response. When POSTing only child entity, must provide in URL PUT: Client provides ThirdPartyPayId for resource updating (within URL), exposed on response DELETE: Client provides ThirdPartyPayId for resource updating (within URL)
JobCode	NO	1	100
LocationDescription	NO	1	25
OrgLevel1	NO	1	50
OrgLevel2	NO	1	50
OrgLevel3	NO	1	50
OrgLevel4	NO	1	50
EarningCurrentAmount	NO	-	-	Allows negative amounts
EarningPayRate	NO	-	-
YtdEarningAmount	NO	-	-	Allows negative amounts
PieceCount	NO	-	-
PieceUnit	NO	1	10
Id	YES	N/A	N/A	GET: Exposed POST: Auto generated by the service, but exposed on response PUT: Client provides ID for resource updating (within URL), exposed on response DELETE: Client provides ID for resource updating (within URL)
SystemId	NO	1	36	Can be used to store the unique Id of system that data originated from
YtdEarningHours	NO	-	-

Table 3. External Pay Deductions
Property	Required	Min Length	Max Length	Notes
DeductionCode	NO	1	25	If only deduction code is provided, code displays on Third-Party Pay page
DeductionDescription	NO	1	50	If only deduction description is provided, description displays on Third-Party Pay page If deduction code and description are provided, description displays If neither deduction code or description is provided, will display blank
ThirdPartyPayId	YES	N/A	N/A	GET: Exposed POST: Auto generated by the service, but exposed on response. When POSTing only child entity, must provide in URL PUT: Client provides ThirdPartyPayId for resource updating (within URL), exposed on response DELETE: Client provides ThirdPartyPayId for resource updating (within URL)
EmployeeDeductionAmount	NO	-	-	Allows negative amounts
EmployerDeductionAmount	NO	-	-	Allows negative amounts
YtdEmployeeDeductionAmount	NO	-	-	Allows negative amounts
YtdEmployerDeductionAmount	NO	-	-	Allows negative amounts
Id	YES	N/A	N/A	GET: Exposed POST: Auto generated by the service, but exposed on response PUT: Client provides Id for resource updating (within URL), exposed on response DELETE: Client provides ID for resource updating (within URL)
SystemId	NO	1	36	Can be used to store the unique Id of system that data originated from

Table 4. External Pay Taxes
Property	Required	Min Length	Max Length	Notes
ThirdPartyPayId	YES	N/A	N/A	GET: Exposed POST: Auto generated by the service, but exposed on response. When POSTing only child entity, must provide in URL PUT: Client provides ThirdPartyPayId for resource updating (within URL), exposed on response DELETE: Client provides ThirdPartyPayId for resource updating (within URL)
IsEmployerTax	NO	1	1	Y or N value not case sensitive. Defaults to N.
CurrentTaxableWages	NO	-	-	Allows negative amounts
CurrentTaxAmount	NO	-	-	Allows negative amounts
YtdTaxableWages	NO	-	-	Allows negative amounts
YtdTaxAmount	NO	-	-	Allows negative amounts
Id	YES	N/A	N/A	GET: Exposed POST: Auto generated by the service, but exposed on response PUT: Client provides Id for resource updating (within URL), exposed on response also DELETE: Client provides Id for resource updating (within URL)
SystemId	NO	1	36	Can be used to store the unique Id of system that data originated from
TaxCode	NO	1	25	If only tax code is provided, code displays on Third-Party Pay page
TaxDescription	NO	1	50	If only tax description is provided, description displays on Third-Party Pay page.
TypeOfTax	NO	1	10	If only type of tax is provided, type of tax displays on Third-Party Pay page If tax description, code, and type of tax are provided, description displays If tax description and type of tax are provided, description displays If tax code and type of tax are provided, code displays If tax code and description are provided, description displays If neither tax description, code, or type of tax are provided, will display blank

Table 5. External Pay Distribution
Property	Required	Min Length	Max Length	Notes
DirectDepositAccountNumber	NO	1	22
ThirdPartyPayId	YES	N/A	N/A	GET: Exposed POST: Auto generated by the service, but exposed on response. When POSTing only child entity, must provide in URL PUT: Client provides ThirdPartyPayId for resource updating (within URL), exposed on response DELETE: Client provides ThirdPartyPayId for resource updating (within URL)
DirectDepositAmount	NO	-	-	Allows negative amounts
Id	YES	N/A	N/A	GET: Exposed POST: Auto generated by the service, but exposed on response PUT: Client provides Id for resource updating (within URL), exposed on response DELETE: Client provides Id for resource updating (within URL)
SystemId	NO	1	36	can be used to store the unique Id of system that data originated from

Header

To initially log in to the ThirdPartyPay service, the username and password for the UKG Pro Web Service Account can be sent for basic authorization.

The format is username:password (note the colon between the credentials). The credentials in this format must then be encoded using standard base64 encoding. The initial call to the service should contain a header as follows:

Basic Auth Example

Authorization: basic dXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/json; odata=verbose
Content-Type: application/json
US-Customer-Api-Key: YOUR COMPANY’S API KEY

The return from this call will contain a US-SessionId. This token should be included in the header of subsequent calls to the service.

Example

US-SessionId: 1807a7d3-1fdd-4c14-835b-59b178a323ec
Accept: application/json
Content-Type: application/json
US-Customer-Api-Key: YOUR COMPANY’S API KEY

GET

Returns all Third-Party Pay information, including: earnings, deductions, taxes and distributions.

Resource URL: https://servername/services/payroll/v1/thirdpartypay

Sample Return from GET

{
    "d": {
        "results": [
            {
                "__metadata": {
                    "id": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')",
                    "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')",
                    "type": "UltimateSoftware.Foundation.Services.PayrollApi.Models.ThirdPartyPay"
                },
                "Deductions": {
                    "__deferred": {
                        "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Deductions"
                    }
                },
                "Distributions": {
                    "__deferred": {
                        "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Distributions"
                    }
                },
                "Earnings": {
                    "__deferred": {
                        "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Earnings"
                    }
                },
                "Taxes": {
                    "__deferred": {
                        "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Taxes"
                    }
                },
                "Id": "A7ILCE0000K0",
                "AddressLine1": "TestAddressLine1",
                "AddressLine2": "TestAddressLine2",
                "AddressMunicipality": "TestAddressMunicipality",
                "AddressRegion": "TestAddressRegion",
                "CheckAddModeCode": "A",
                "CheckNumber": "12345",
                "CountryCode": "USA",
                "DocumentNumber": "TestDocumentNumber",
                "EmployeeIdentifier": {
                    "__metadata": {
                        "type": "UltimateSoftware.Foundation.Services.ApiCore.Models.EmployeeIdentifier"
                    },
                    "Type": "EmployeeNumber",
                    "Value": "123456789",
                    "CompanyIdentifier": {
                        "__metadata": {
                            "type": "UltimateSoftware.Foundation.Services.ApiCore.Models.CompanyIdentifier"
                        },
                        "Type": "CompanyCode",
                        "Value": "C0014"
                    }
                },
                "EmployeeNumber": "TestEmployeeNumber",
                "IsVoided": "N",
                "NameFirst": "TestNameFirst",
                "NameLast": "TestNameLast",
                "CheckAmount": "100.0000",
                "CurrentNetPay": "100.0000",
                "CurrencyCode": "USD",
                "TotalCurrentDeductions": "100.0000",
                "TotalCurrentEarnings": "100.0000",
                "TotalCurrentTaxes": "100.0000",
                "TotalYtdDeductions": "100.0000",
                "TotalYtdEarnings": "100.0000",
                "TotalYtdNetPay": "100.0000",
                "TotalYtdTaxes": "100.0000",
                "PayCompanyIdentifier": {
                    "__metadata": {
                        "type": "UltimateSoftware.Foundation.Services.ApiCore.Models.CompanyIdentifier"
                    },
                    "Type": "CompanyCode",
                    "Value": "C0014"
                },
                "PayDate": "2014-06-20T11:21:20.07",
                "PayGroupCode": "HUBW1 ",
                "PayrollCountryCode": "USA",
                "PeriodControl": "999999999",
                "PeriodEndDate": "2014-06-20T11:21:20.07",
                "PeriodStartDate": "2014-06-20T11:21:20.07",
                "PostalCode": "TestPostalCode",
                "SourceSystem": "TestSource",
                "SystemId": "TestSystemId",
                "DateTimeChanged": "2014-07-24T13:29:05.573",
                "DateTimeCreated": "2014-07-24T13:29:05.573",
                "JobCode": "TestJobCode",
                "LocationDescription": "TestLocationDescription",
                "OrgLevel1": "TestOrgLevel1",
                "OrgLevel2": "TestOrgLevel2",
                "OrgLevel3": "TestOrgLevel3",
                "OrgLevel4": "TestOrgLevel4"
            },
            {
                "__metadata": {
                    "id": "http://servername/services/payroll/v1/thirdpartypay('A7Q48V0000K0')",
                    "uri": "http://servername/services/payroll/v1/thirdpartypay('A7Q48V0000K0')",
                    "type": "UltimateSoftware.Foundation.Services.PayrollApi.Models.ThirdPartyPay"
                },
                "Deductions": {
                    "__deferred": {
                        "uri": "http://servername/services/payroll/v1/thirdpartypay('A7Q48V0000K0')/Deductions"
                    }
                },
                "Distributions": {
                    "__deferred": {
                        "uri": "http://servername/services/payroll/v1/thirdpartypay('A7Q48V0000K0')/Distributions"
                    }
                },
                "Earnings": {
                    "__deferred": {
                        "uri": "http://servername/services/payroll/v1/thirdpartypay('A7Q48V0000K0')/Earnings"
                    }
                },
                "Taxes": {
                    "__deferred": {
                        "uri": "http://servername/services/payroll/v1/thirdpartypay('A7Q48V0000K0')/Taxes"
                    }
                },
                "Id": "A7Q48V0000K0",
                "AddressLine1": "TestAddressLine1",
                "AddressLine2": "TestAddressLine2",
                "AddressMunicipality": "TestAddressMunicipality",
                "AddressRegion": "TestAddressRegion",
                "CheckAddModeCode": "A",
                "CheckNumber": "12345",
                "CountryCode": "USA",
                "DocumentNumber": "TestDocumentNumber",
                "EmployeeIdentifier": {
                    "__metadata": {
                        "type": "UltimateSoftware.Foundation.Services.ApiCore.Models.EmployeeIdentifier"
                    },
                    "Type": "EmployeeNumber",
                    "Value": "123456789",
                    "CompanyIdentifier": {
                        "__metadata": {
                            "type": "UltimateSoftware.Foundation.Services.ApiCore.Models.CompanyIdentifier"
                        },
                        "Type": "CompanyCode",
                        "Value": "C0014"
                    }
                },
                "EmployeeNumber": "TestEmployeeNumber",
                "IsVoided": "N",
                "NameFirst": "TestNameFirst",
                "NameLast": "TestNameLast",
                "CheckAmount": "100.0000",
                "CurrentNetPay": "100.0000",
                "CurrencyCode": "USD",
                "TotalCurrentDeductions": "100.0000",
                "TotalCurrentEarnings": "100.0000",
                "TotalCurrentTaxes": "100.0000",
                "TotalYtdDeductions": "100.0000",
                "TotalYtdEarnings": "100.0000",
                "TotalYtdNetPay": "100.0000",
                "TotalYtdTaxes": "100.0000",
                "PayCompanyIdentifier": {
                    "__metadata": {
                        "type": "UltimateSoftware.Foundation.Services.ApiCore.Models.CompanyIdentifier"
                    },
                    "Type": "CompanyCode",
                    "Value": "C0014"
                },
                "PayDate": "2014-06-20T11:21:20.07",
                "PayGroupCode": "HUBW1 ",
                "PayrollCountryCode": "USA",
                "PeriodControl": "999999999",
                "PeriodEndDate": "2014-06-20T11:21:20.07",
                "PeriodStartDate": "2014-06-20T11:21:20.07",
                "PostalCode": "TestPostalCode",
                "SourceSystem": "TestSource",
                "SystemId": "TestSystemId",
                "DateTimeChanged": "2014-07-28T15:00:34.533",
                "DateTimeCreated": "2014-07-28T15:00:34.533",
                "JobCode": "TestJobCode",
                "LocationDescription": "TestLocationDescription",
                "OrgLevel1": "TestOrgLevel1",
                "OrgLevel2": "TestOrgLevel2",
                "OrgLevel3": "TestOrgLevel3",
                "OrgLevel4": "TestOrgLevel4"
            }
        ]
    }
}

GET with Third-Party Pay ID - Optional

Filters the return to include only the Third-Party Pay record with the id number indicated as the id parameter.

Resource URL: https://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')

Sample Return from GET

{
    "d": {
        "__metadata": {
            "id": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')",
            "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')",
            "type": "UltimateSoftware.Foundation.Services.PayrollApi.Models.ThirdPartyPay"
        },
        "Deductions": {
            "__deferred": {
                "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Deductions"
            }
        },
        "Distributions": {
            "__deferred": {
                "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Distributions"
            }
        },
        "Earnings": {
            "__deferred": {
                "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Earnings"
            }
        },
        "Taxes": {
            "__deferred": {
                "uri": "http://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Taxes"
            }
        },
        "Id": "A7ILCE0000K0",
        "AddressLine1": "TestAddressLine1",
        "AddressLine2": "TestAddressLine2",
        "AddressMunicipality": "TestAddressMunicipality",
        "AddressRegion": "TestAddressRegion",
        "CheckAddModeCode": "A",
        "CheckNumber": "12345",
        "CountryCode": "USA",
        "DocumentNumber": "TestDocumentNumber",
        "EmployeeIdentifier": {
            "__metadata": {
                "type": "UltimateSoftware.Foundation.Services.ApiCore.Models.EmployeeIdentifier"
            },
            "Type": "EmployeeNumber",
            "Value": "123456789",
            "CompanyIdentifier": {
                "__metadata": {
                    "type": "UltimateSoftware.Foundation.Services.ApiCore.Models.CompanyIdentifier"
                },
                "Type": "CompanyCode",
                "Value": "C0014"
            }
        },
        "EmployeeNumber": "TestEmployeeNumber",
        "IsVoided": "N",
        "NameFirst": "TestNameFirst",
        "NameLast": "TestNameLast",
        "CheckAmount": "100.0000",
        "CurrentNetPay": "100.0000",
        "CurrencyCode": "USD",
        "TotalCurrentDeductions": "100.0000",
        "TotalCurrentEarnings": "100.0000",
        "TotalCurrentTaxes": "100.0000",
        "TotalYtdDeductions": "100.0000",
        "TotalYtdEarnings": "100.0000",
        "TotalYtdNetPay": "100.0000",
        "TotalYtdTaxes": "100.0000",
        "PayCompanyIdentifier": {
            "__metadata": {
                "type": "UltimateSoftware.Foundation.Services.ApiCore.Models.CompanyIdentifier"
            },
            "Type": "CompanyCode",
            "Value": "C0014"
        },
        "PayDate": "2014-06-20T11:21:20.07",
        "PayGroupCode": "HUBW1 ",
        "PayrollCountryCode": "USA",
        "PeriodControl": "999999999",
        "PeriodEndDate": "2014-06-20T11:21:20.07",
        "PeriodStartDate": "2014-06-20T11:21:20.07",
        "PostalCode": "TestPostalCode",
        "SourceSystem": "TestSource",
        "SystemId": "TestSystemId",
        "DateTimeChanged": "2014-07-24T13:29:05.573",
        "DateTimeCreated": "2014-07-24T13:29:05.573",
        "JobCode": "TestJobCode",
        "LocationDescription": "TestLocationDescription",
        "OrgLevel1": "TestOrgLevel1",
        "OrgLevel2": "TestOrgLevel2",
        "OrgLevel3": "TestOrgLevel3",
        "OrgLevel4": "TestOrgLevel4"
    }
}

GET Specific Child Type - Optional

Filters the return to include all child records for the indicated type (Earnings, Deductions, Taxes or Distributions).

Resource URL: https://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Deductions

Sample Return from GET

{
    "d": {
        "results": [
            {
                "__metadata": {
                    "id": "http://servername/services/payroll/v1/thirdpartypay(‘A7ILCE0000K0’)/Deductions(1)",
                    "uri": "http://servername/services/payroll/v1/thirdpartypay(‘A7ILCE0000K0’)/Deductions(1)",
                    "type": "UltimateSoftware.Foundation.Services.PayrollApi.Models.Deduction"
                },
                "Id": 1,
                "ThirdPartyPayId": "A7ILCE0000K0",
                "DeductionCode": "TestDeductionCode",
                "DeductionDescription": "TestDeductionDescription",
                "EmployeeDeductionAmount": "100.0000",
                "EmployerDeductionAmount": "100.0000",
                "YtdEmployeeDeductionAmount": "100.0000",
                "YtdEmployerDeductionAmount": "100.0000",
                "SystemId": "TestSystemId"
            },
            {
                "__metadata": {
                    "id": "http://servername/services/payroll/v1/thirdpartypay(‘A7ILCE0000K0’)/Deductions(2)",
                    "uri": "http://servername/services/payroll/v1/thirdpartypay(‘A7ILCE0000K0’)/Deductions(2)",
                    "type": "UltimateSoftware.Foundation.Services.PayrollApi.Models.Deduction"
                },
                "Id": 2,
                "ThirdPartyPayId": "A7ILCE0000K0",
                "DeductionCode": "2TestDeductionCode",
                "DeductionDescription": "2TestDeductionDescription",
                "EmployeeDeductionAmount": "225.0000",
                "EmployerDeductionAmount": "150.0000",
                "YtdEmployeeDeductionAmount": "225.0000",
                "YtdEmployerDeductionAmount": "150.0000",
                "SystemId": null
            }
        ]
    }
}

GET with Child ID - Optional

Filters the return to include only the child record (Earnings, Deductions, Taxes or Distributions) with the id number indicated as the id parameter.

Resource URL: https://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Deductions(1)

Sample Return from GET

{
    "d": {
        "__metadata": {
                          "id": "http://servername/services/payroll/v1/thirdpartypay(‘A7ILCE0000K0’)/Deductions(1)",
                          "uri": "http://servername/services/payroll/v1/thirdpartypay(‘A7ILCE0000K0’)/Deductions(1)",

            "type": "UltimateSoftware.Foundation.Services.PayrollApi.Models.Deduction"
        },
        "Id": 1,
        "ThirdPartyPayId": "A7ILCE0000K0",
        "DeductionCode": "TestDeductionCode",
        "DeductionDescription": "TestDeductionDescription",
        "EmployeeDeductionAmount": "100.0000",
        "EmployerDeductionAmount": "100.0000",
        "YtdEmployeeDeductionAmount": "100.0000",
        "YtdEmployerDeductionAmount": "100.0000",
        "SystemId": "TestSystemId"
    }
}

POST

Inserts a Third-Party Pay record.

Resource URL: https://servername/services/payroll/v1/thirdpartypay

Sample POST

{
    "AddressLine1": "TestAddressLine1",
    "AddressLine2": "TestAddressLine2",
    "AddressMunicipality": "TestAddressMunicipality",
    "AddressRegion": "TestAddressRegion",
    "CheckAddModeCode": "A",
    "CheckNumber": "12345",
    "CountryCode": "USA",
    "DocumentNumber": "TestDocumentNumber",
    "EmployeeIdentifier": {
        "Type": "EmployeeId",
        "Value": "9MT3O30000K0",
        "CompanyIdentifier": {
            "Type": "CompanyCode",
            "Value": "SGWSF"
        }
    },
    "EmployeeNumber": "257082178",
    "IsVoided": "N",
    "CurrencyCode": "USD",
    "CheckAmount": "545.27",
    "CurrentNetPay": "502.43",
    "TotalCurrentDeductions": "100.0",
    "TotalCurrentEarnings": "100.0",
    "TotalCurrentTaxes": "100.0",
    "TotalYtdDeductions": "100.0",
    "TotalYtdEarnings": "100.0",
    "TotalYtdNetPay": "100.0",
    "TotalYtdTaxes": "100.0",
    "PayCompanyIdentifier": {
        "Type": "CompanyCode",
        "Value": "SGWSF"
    },
    "PayDate": "2014-05-15T11:21:20.0686729-04:00",
    "PayGroupCode": "SGPWSF",
    "PayrollCountryCode": "SGP",
    "PeriodControl": "999999999",
    "PeriodEndDate": "2013-01-31T11:21:20.069673-04:00",
    "PeriodStartDate": "2013-01-01T11:21:20.069673-04:00",
    "PostalCode": "TestPostalCode",
    "SourceSystem": "Celergo",
    "SystemId": "TestSystemId",
    "JobCode": "TestJobCode",
    "LocationDescription": "TestLocationDescription",
    "OrgLevel1": "TestOrgLevel1",
    "OrgLevel2": "TestOrgLevel2",
    "OrgLevel3": "TestOrgLevel3",
    "OrgLevel4": "TestOrgLevel4",
    "Deductions": [
        {
            "DeductionCode": "TestDeductionCode",
            "DeductionDescription": "TestDeductionDescription",
            "EmployeeDeductionAmount": "100.0",
            "EmployerDeductionAmount": "100.0",
            "YtdEmployeeDeductionAmount": "100.0",
            "YtdEmployerDeductionAmount": "100.0",
            "SystemId": "TestSystemId"
        }
    ],
    "Distributions": [
        {
            "DirectDepositAccountNumber": "TestAccountNumber",
            "DirectDepositAmount": "100",
            "SystemId": "TestSystemId"
        }
    ],
    "Earnings": [
        {
            "EarningCode": "TestEarningCode",
            "EarningDescription": "TestEarningDescription",
            "EarningHours": "40",
            "ExcludeInTotalHours": "Y",
            "JobCode": "TestJobCode",
            "LocationDescription": "TestLocationDescription",
            "OrgLevel1": "TestOrgLevel1",
            "OrgLevel2": "TestOrgLevel2",
            "OrgLevel3": "TestOrgLevel3",
            "OrgLevel4": "TestOrgLevel4",
            "EarningCurrentAmount": "40",
            "EarningPayRate": "40",
            "YtdEarningAmount": "40",
            "PieceCount": "1.0",
            "PieceUnit": "TestPUnit",
            "SystemId": "TestSystemId",
            "YtdEarningHours": "100.0"
        }
    ],
    "Taxes": [
        {
            "IsEmployerTax": "Y",
            "CurrentTaxableWages": "100.0",
            "CurrentTaxAmount": "100.0",
            "YtdTaxableWages": "100.0",
            "YtdTaxAmount": "100.0",
            "SystemId": "TestSystemId",
            "TaxCode": "TestTaxCode",
            "TaxDescription": "TestTaxDescription",
            "TypeOfTax": "TestTaxTp"
        }
    ]
}

POST Child Only

Inserts the child record specified (Earnings, Deductions, Taxes or Distributions) and associates it to the Third-Party Pay record specified.

Resource URL: https://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Deductions

Sample POST

{
    "DeductionCode": "3TestDeductionCode",
    "DeductionDescription": "3TestDeductionDescription",
    "EmployeeDeductionAmount": "333.0",
    "EmployerDeductionAmount": "350.0",
    "YtdEmployeeDeductionAmount": "333.0",
    "YtdEmployerDeductionAmount": "350.0",
    "SystemId": null
}

PUT with Third-Party Pay and Child ID

Updates the child record specified (Earnings, Deductions, Taxes or Distributions).

Resource URL: https://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')/Deductions(1)

Sample PUT

{
    "DeductionCode": "UpdateDeductionCode",
    "DeductionDescription": "TestDeductionDescription",
    "EmployeeDeductionAmount": "200.0000",
    "EmployerDeductionAmount": "100.0000",
    "YtdEmployeeDeductionAmount": "200.0000",
    "YtdEmployerDeductionAmount": "100.0000",
    "SystemId": "TestSystemId"
}

PUT with Third-Party Pay Only

Updates the third-party pay record specified.

Note You cannot perform a PUT for a parent and a child within the same request.

Resource URL: https://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')

Sample PUT

{
    "AddressLine1": "TestAddressLine1",
    "AddressLine2": "TestAddressLine2",
    "AddressMunicipality": "TestAddressMunicipality",
    "AddressRegion": "TestAddressRegion",
    "CheckAddModeCode": "A",
    "CheckNumber": "12345",
    "CountryCode": "USA",
    "DocumentNumber": "TestDocumentNumber",
    "EmployeeIdentifier": {
        "Type": "EmployeeId",
        "Value": "9MT3O30000K0",
        "CompanyIdentifier": {
            "Type": "CompanyCode",
            "Value": "SGWSF"
        }
    },
    "EmployeeNumber": "257082178",
    "IsVoided": "N",
    "CurrencyCode": "USD",
    "CheckAmount": "545.27",
    "CurrentNetPay": "502.43",
    "TotalCurrentDeductions": "100.0",
    "TotalCurrentEarnings": "100.0",
    "TotalCurrentTaxes": "100.0",
    "TotalYtdDeductions": "100.0",
    "TotalYtdEarnings": "100.0",
    "TotalYtdNetPay": "100.0",
    "TotalYtdTaxes": "100.0",
    "PayCompanyIdentifier": {
        "Type": "CompanyCode",
        "Value": "SGWSF"
    },
    "PayDate": "2014-05-15T11:21:20.0686729-04:00",
    "PayGroupCode": "SGPWSF",
    "PayrollCountryCode": "SGP",
    "PeriodControl": "999999999",
    "PeriodEndDate": "2013-01-31T11:21:20.069673-04:00",
    "PeriodStartDate": "2013-01-01T11:21:20.069673-04:00",
    "PostalCode": "TestPostalCode",
    "SourceSystem": "Celergo",
    "SystemId": "TestSystemId",
    "JobCode": "TestJobCode",
    "LocationDescription": "TestLocationDescription",
    "OrgLevel1": "TestOrgLevel1",
    "OrgLevel2": "TestOrgLevel2",
    "OrgLevel3": "TestOrgLevel3",
    "OrgLevel4": "TestOrgLevel4"
}

DELETE with Third-Party Pay ID

Deletes the third-party pay record.

Resource URL: https://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0')

DELETE with Third-Party Pay and Child ID

Deletes the child record for the specified third-party pay record.

Resource URL: https://servername/services/payroll/v1/thirdpartypay('A7ILCE0000K0') /Deductions(1)

Possible Return Values

The following return values are possible.


Return Code	Meaning
200 OK	The request has succeeded (for instance on a GET).
201 Created	The POST was successful and a new record was created.
204 No Content	The PUT was successful and the record was updated. *
400 Bad Request	The request was malformed, unable to be understood or contained validation errors. **
401 Unauthorized	The credentials provided were not able to be authenticated.
403 Forbidden	Access to the requested resource is denied.
404 Not Found	The requested URI cannot be found.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
501 Not Implemented	The request is not supported.

* 204 No Content (return-no-content) is the default behavior. This can be changed to return the content of the successful PUT by altering the header (return-content). The syntax for the Prefer header is as follows:

Prefer       =  "Prefer" ":" preference 

preference   =  "return-no-content" |
                "return-content" |
                preference-extension

preference-extension =  prefer-params *( ";" prefer-params ])
prefer-params =  token [ "=" ( token | quoted-string )

** 400 Bad Request validation error details will be contained in the content of the response.

© UKG Inc. All rights reserved. For a full list of UKG trademarks, visit www.ukg.com/trademarks. All other trademarks, if any, are the property of their respective owners. No part of this document or its content may be reproduced in any form or by any means or stored in a database or retrieval system without the prior written authorization of UKG Inc. (“UKG”). Information in this document is subject to change without notice. The document and its content are confidential information of UKG and may not be disseminated to any third party. Nothing herein constitutes legal advice, tax advice, or any other advice. All legal or tax questions or concerns should be directed to your legal counsel or tax consultant.

Liability/Disclaimer

UKG makes no representation or warranties with respect to the accuracy or completeness of the document or its content and specifically disclaims any responsibility or representation for other vendors’ software. The terms and conditions of your agreement with us regarding the software or services provided by us, which is the subject of the documentation contained herein, govern this document or content. All company, organization, person, and event references are fictional. Any resemblance to actual companies, organizations, persons, and events is entirely coincidental.

Links to Other Materials: The linked sites and embedded links are not under the control of UKG. We reserve the right to terminate any link or linking program at any time. UKG does not endorse companies or products to which it links. If you decide to access any of the third-party sites linked to the site, you do so entirely at your own risk.

UKG Pro Web Services API Guide

Third Party Pay Service

Introduction

Third-Party Pay Service API

Overview

Third-Party Pay Data

Header

Resources and Parameters

GET

GET with Third-Party Pay ID - Optional

GET Specific Child Type - Optional

GET with Child ID - Optional

POST

POST Child Only

PUT with Third-Party Pay and Child ID

PUT with Third-Party Pay Only

DELETE with Third-Party Pay ID

DELETE with Third-Party Pay and Child ID

Possible Return Values