Get employee

get https://apisandbox.paylocity.com/api/v2/companies/{companyId}/employees/{employeeId}

Get Employee API will return employee data currently available in Paylocity Payroll/HR solution.

🚧
Maintenance Mode
This API is in a limited support mode and certain resources will be moved to a sunset status in the next 18-24 months.
The Employee Demographic API should be used when possible in place of the Employee resources of this API

Responses

Response body

object

additionalDirectDeposit

array of objects

length ≤ 19

Add up to 19 direct deposit accounts in addition to the main direct deposit account. IMPORTANT: A direct deposit update will remove ALL existing main and additional direct deposit information in WebPay and replace with information provided on the request. GET API will not return direct deposit data.

additionalDirectDeposit

object

accountNumber

string

Account number, entered without special characters and spaces.
Max length: 17

accountType

string

Account type. Valid values are C (Checking), S (Saving), P (Pay Card).
Max length: 1

amount

number

Amount value to be deposited to the account.
Decimal (12,2)

amountType

string

Amount type to indicate the context of the amount. Common values are F (FLAT), F- (Net Minus), P (Percent).
Max length: 5

blockSpecial

boolean

Indicates if direct deposit should be blocked when special check types such as Bonus are processed.

isSkipPreNote

boolean

Indicates if account will not pre-note.

nameOnAccount

string

Name on the bank account. Defaults to employee's name.
Max length: 30

preNoteDate

string

Date to end the pre-note of the account. Common formats include MM-DD-CCYY, CCYY-MM-DD.

routingNumber

string

ABA Transit Routing Number, entered without dashes or spaces.
Max length: 9

additionalRate

array of objects

Add Additional Rates.

additionalRate

object

changeReason

string

Not required. If populated, must match one of the system coded values available in the Additional Rates Change Reason drop down.

costCenter1

string

Not required. Valid values must match one of the system coded cost centers available in the Additional Rates Cost Center level 1 drop down. This cell must be in a text format.

costCenter2

string

Not required. Valid values must match one of the system coded cost centers available in the Additional Rates Cost Center level 2 drop down. This cell must be in a text format.

costCenter3

string

Not required. Valid values must match one of the system coded cost centers available in the Additional Rates Cost Center level 3 drop down. This cell must be in a text format.

effectiveDate

string

Required. Common formats include MM-DD-CCYY, CCYY-MM-DD.

endCheckDate

string

Not required. Must match one of the system coded check dates available in the Additional Rates End Check Date drop down. Common formats include MM-DD-CCYY, CCYY-MM-DD.

job

string

Not required. If populated, must match one of the system coded values available in the Additional Rates Job drop down.

rate

number

Required. Enter dollar amount that corresponds to the Per selection.

rateCode

string

Required. If populated, must match one of the system coded values available in the Additional Rates Rate Code drop down.

rateNotes

string

Not required.
Max length: 4000

ratePer

string

Required. Valid values are HOUR or WEEK.

shift

string

Not required. If populated, must match one of the system coded values available in the Additional Rates Shift drop down.

benefitSetup

object

Add or update setup values used for employee benefits integration, insurance plan settings, and ACA reporting.

benefitClass

string

Benefit Class code. Values are configured in Web Pay Company > Setup > Benefits > Classes.
Max length: 30

benefitClassEffectiveDate

string

Date when Benefit Class takes effect. Common formats include MM-DD-CCYY, CCYY-MM-DD.

benefitSalary

number

Salary used to configure benefits.
Decimal(12,2)

benefitSalaryEffectiveDate

string

Date when Benefit Salary takes effect. Common formats include MM-DD-CCYY, CCYY-MM-DD.

doNotApplyAdministrativePeriod

boolean

Applicable only for HR Enhanced clients and Benefit Classes with ACA Employment Type of Full Time.

isMeasureAcaEligibility

boolean

Only valid for HR Enhanced clients and Benefit Classes that are ACA Employment Type of Full Time.

birthDate

string

Employee birthdate. Common formats include MM-DD-CCYY, CCYY-MM-DD.

companyName

string

Company name as defined in Web Pay, applicable with GET requests only.
Max length: 50

currency

string

Employee is paid in this currency.
Max length: 30

customBooleanFields

array of objects

length ≤ 8

Up to 8 custom fields of boolean (checkbox) type value.

customBooleanFields

object

category

string

required

The custom field category. Acceptable value is 'PayrollAndHR'.

PayrollAndHR

label

string

required

The custom field label whose value is to be added/updated. Must match to the label defined in Web Pay Custom Fields setup. Max length: 255.

value

boolean

required

The custom boolean field value.

customDateFields

array of objects

length ≤ 8

Up to 8 custom fields of the date type value.

customDateFields

object

category

string

required

The custom field category. Acceptable value is 'PayrollAndHR'.

PayrollAndHR

label

string

required

The custom field label whose value is to be added/updated. Must match to the label defined in Web Pay Custom Fields setup. Max length: 255.

value

string

required

The custom date field value. Common formats include MM-DD-CCYY, CCYY-MM-DD.

customDropDownFields

array of objects

length ≤ 8

Up to 8 custom fields of the dropdown type value.

customDropDownFields

object

category

string

required

The custom field category. Acceptable value is 'PayrollAndHR'.

PayrollAndHR

label

string

required

The custom field label whose value is to be added/updated. Must match to the label defined in Web Pay Custom Fields setup. Max length: 255.

value

string

required

The custom dropdown field value. Values are configured in Web Pay Company > Setup > List Values > Lookup Values > Custom Fields: PayrollAndHR. Max length: 10.

customNumberFields

array of objects

length ≤ 8

Up to 8 custom fields of numeric type value.

customNumberFields

object

category

string

required

The custom field category. Acceptable value is 'PayrollAndHR'.

PayrollAndHR

label

string

required

The custom field label whose value is to be added/updated. Must match to the label defined in Web Pay Custom Fields setup. Max length: 255.

value

number

required

The custom number field value. Decimal (18,6).

customTextFields

array of objects

length ≤ 8

Up to 8 custom fields of text type value.

customTextFields

object

category

string

required

The custom field category. Acceptable value is 'PayrollAndHR'.

PayrollAndHR

label

string

required

The custom field label whose value is to be added/updated. Must match to the label defined in Web Pay Custom Fields setup. Max length: 255.

value

string

required

The custom text field value. Max length: 255.

departmentPosition

object

Add or update home department cost center, position, supervisor, reviewer, employment type, EEO class, pay settings, and union information.

changeReason

string

Employee department/position change reason. Must match Company setup.
Max length: 15

clockBadgeNumber

string

Employee clock badge number. Defaults to employeeId.
Max length: 10

costCenter1

string

Employer defined location, like branch, division, department, etc. Must match Company setup.
Max length: 10

costCenter2

string

Employer defined location, like branch, division, department, etc. Must match Company setup.
Max length: 10

costCenter3

string

Employer defined location, like branch, division, department, etc. Must match Company setup.
Max length: 10

effectiveDate

string

The date the position takes effect. Common formats include MM-DD-CCYY, CCYY-MM-DD.

employeeType

string

Employee current employment type. Common values RFT (Regular Full Time), RPT (Regular Part Time), SNL (Seasonal), TFT (Temporary Full Time), TPT (Temporary Part Time).
Max length: 10

equalEmploymentOpportunityClass

string

Values are configured in Company > Setup > HR > EEO Classes.
Max length: 10

isMinimumWageExempt

boolean

Indicates if employee is exempt from minimum wage.

isOvertimeExempt

boolean

Indicates if employee is exempt from overtime.

isSupervisorReviewer

boolean

Indicates if employee is a supervisor or reviewer.

isUnionDuesCollected

boolean

Indicates if union dues are collected.

isUnionInitiationCollected

boolean

Indicates if initiations fees are collected.

jobTitle

string

Employee current job title.
Max length: 50

payGroup

string

Employee pay group. Must match Company setup.
Max length: 20

positionCode

string

Employee position code. Must match Company setup.
Max length: 20

reviewerCompanyNumber

string

Company number of reviewer.
Max length: 9

reviewerEmployeeId

string

Employee id of the reviewer.
Max length: 10

shift

string

Employee work shift.
Max length: 255

supervisorCompanyNumber

string

Supervisor's company number. Defaults to employee company number.
Max length: 9

supervisorEmployeeId

string

EmployeeId of the supervisor.
Max length: 10

tipped

string

Indicates if employee receives tips.

unionAffiliationDate

string

Employee union affiliation effective date. Common formats include MM-DD-CCYY, CCYY-MM-DD.

unionCode

string

Employee union code. Must match Company setup.
Max length: 10

unionPosition

string

Employee union position. Must match Company setup.
Max length: 30

workersCompensation

string

Employee worker compensation code. Must match Company setup.
Max length: 10

disabilityDescription

string

Indicates if employee has disability status.

emergencyContacts

array of objects

Add or update Emergency Contacts.

emergencyContacts

object

address1

string

1st address line.

address2

string

2nd address line.

city

string

City.

country

string

County.

county

string

Country. Must be a valid 3 character country code. Common values are USA (United States), CAN (Canada).

string

Contact email. Must be valid email address format.

firstName

string

required

Required. Contact first name.
Max length: 40

homePhone

string

Contact Home Phone. Valid phone format (###) ####### or ######-#### or ### ### #### or ########## or, if international, starts with +#, only spaces and digits allowed.

lastName

string

required

Required. Contact last name.
Max length: 40

mobilePhone

string

Contact Mobile Phone. Valid phone format (###) ####### or ######-#### or ### ### #### or ########## or, if international, starts with +#, only spaces and digits allowed.

notes

string

Notes.
Max length: 1000

pager

string

Contact Pager. Valid phone format (###) ####### or ######-#### or ### ### #### or ########## or, if international, starts with +#, only spaces and digits allowed.

primaryPhone

string

Required. Contact primary phone type. Must match Company setup. Valid values are H (Home), M (Mobile), P (Pager), W (Work)

priority

string

Required. Contact priority. Valid values are P (Primary) or S (Secondary).

relationship

string

Required. Contact relationship. Must match Company setup. Common values are Spouse, Mother, Father.

state

string

State or Province. If U.S. address, must be valid 2 character state code. Common values are IL (Illinois), CA (California).

syncEmployeeInfo

boolean

Valid values are true or false.

workExtension

string

Work Extension.

workPhone

string

Contact Work Phone. Valid phone format (###) ####### or ######-#### or ### ### #### or ########## or, if international, starts with +#, only spaces and digits allowed.

zip

string

Postal code. If U.S. address, must be a valid zip code.

employeeId

string

Leave blank to have Web Pay automatically assign the next available employee ID.
Max length: 10

ethnicity

string

Employee ethnicity.
Max length: 10

federalTax

object

Add or update federal tax amount type (taxCalculationCode), amount or percentage, filing status, and exemptions.

amount

number

Tax amount.
Decimal (12,2)

exemptions

number

Federal tax exemptions value.
Decimal (12,2)

filingStatus

string

Employee federal filing status. Common values are S (Single), M (Married).
Max length: 50

percentage

number

Tax percentage.
Decimal (12,2)

taxCalculationCode

string

Tax calculation code. Common values are F (Flat), P (Percentage), FDFP (Flat Dollar Amount plus Fixed Percentage).
Max length: 10

firstName

string

Employee first name.
Max length: 40

gender

string

Employee gender. Common values M (Male), F (Female).
Max length: 1

homeAddress

object

Add or update employee's home address, personal phone numbers, and personal email.

address1

string

1st address line.
Max length: 40

address2

string

2nd address line.
Max length: 40

city

string

City.
Max length: 40

country

string

Country.
Max length: 30

county

string

County.
Max length: 30

emailAddress

string

Email.
Max length: 50

mobilePhone

string

Mobile phone number.
Max length: 12

phone

string

Phone number.
Max length: 12

postalCode

string

Postal code.
Max length: 10

state

string

State or province.
Max length: 2

isHighlyCompensated

boolean

Indicates if employee meets the highly compensated employee criteria.

isSmoker

boolean

Indicates if employee is a smoker.

lastName

string

Employee last name.
Max length: 40

localTax

array of objects

length ≤ 5

Add, update, or delete local tax code, filing status, and exemptions including PA-PSD taxes.

localTax

object

exemptions

number

Local tax exemptions value.
Decimal (12,2)

exemptions2

number

Local tax exemptions 2 value.
Decimal (12,2)

filingStatus

string

Employee local tax filing status. Must match specific local tax setup.
Max length: 50

residentPSD

string

Resident PSD (political subdivision code) applicable in PA. Must match Company setup.
Max length: 9

taxCode

string

Local tax code.
Max length: 50

workPSD

string

Work location PSD. Must match Company setup.
Max length: 9

mainDirectDeposit

object

Add the main direct deposit account. After deposits are made to any additional direct deposit accounts, the remaining net check is deposited in the main direct deposit account. IMPORTANT: A direct deposit update will remove ALL existing main and additional direct deposit information in WebPay and replace with what is provided on the request. GET API will not return direct deposit data.

accountNumber

string

Account number, entered without special characters and spaces.
Max length: 17

accountType

string

Account type. Valid values are C (Checking), S (Saving), P (Pay Card).
Max length: 1

blockSpecial

boolean

Indicates if direct deposit should be blocked when special check types such as Bonus are processed.

isSkipPreNote

boolean

Indicates if account will not pre-note.

nameOnAccount

string

Name on the bank account. Defaults to employee's name.
Max length: 30

preNoteDate

string

Date to end the pre-note of the account. Common formats include MM-DD-CCYY, CCYY-MM-DD.

routingNumber

string

ABA Transit Routing Number, entered without dashes or spaces.
Max length: 9

maritalStatus

string

Employee marital status. Common values D (Divorced), M (Married), S (Single), W (Widowed).
Max length: 10

middleName

string

Employee middle name.
Max length: 20

nonPrimaryStateTax

object

Add or update non-primary state tax code, amount type (taxCalculationCode), amount or percentage, filing status, exemptions, supplemental check (specialCheckCalc), and reciprocity code information.

amount

number

State tax code.
Max length: 50

exemptions

number

State tax exemptions value.
Decimal (12,2)

exemptions2

number

State tax exemptions 2 value.
Decimal (12,2)

filingStatus

string

Employee state tax filing status. Common values are S (Single), M (Married).
Max length: 50

percentage

number

State Tax percentage.
Decimal (12,2)

reciprocityCode

string

Non-primary state tax reciprocity code.
Max length: 50

specialCheckCalc

string

Supplemental check calculation code. Common values are Blocked (Taxes blocked on Supplemental checks), Supp (Use supplemental Tax Rate-Code).
Max length: 10

taxCalculationCode

string

Tax calculation code. Common values are F (Flat), P (Percentage), FDFP (Flat Dollar Amount plus Fixed Percentage).
Max length: 10

taxCode

string

State tax code.
Max length: 50

ownerPercent

number

Percentage of employee's ownership in the company, entered as a whole number.
Decimal (12,2)

preferredName

string

Employee preferred display name.
Max length: 20

primaryPayRate

object

Add or update hourly or salary pay rate, effective date, and pay frequency.

annualSalary

number

Employee annual salary.
Decimal (12,2)

baseRate

number

Employee base rate, used for Hourly employees.
Decimal (12,2)

beginCheckDate

string

The date of the first check on which the new pay rate will appear. This value is only applicable when updating an existing employee. Common formats include MM-DD-CCYY, CCYY-MM-DD.

changeReason

string

Pay rate change reason.
Max length: 30

defaultHours

number

Employee default hours consistently worked. If autoPayType is set to D, employee will be paid hourly base rate for the defaultHours.
Decimal (12,2)

effectiveDate

string

The date the employee's pay rate takes effect. Common formats include MM-DD-CCYY, CCYY-MM-DD.

isAutoPay

boolean

If set to True, employee will be paid automatically using deafultHours.

payFrequency

string

Employee current pay frequency. Common values are A (Annual), B (Bi-Weekly), D (Daily), M (Monthly), S (Semi-Monthly), Q (Quarterly), W (Weekly).
Max length: 5

payGrade

string

Employee pay grade. Must match Company setup.
Max length: 10

payRateNote

string

Pay rate notes regarding employee.
Max length: 250

payType

string

Employee pay type (rate code). Valid values are Hourly or Salary.
Max length: 10

ratePer

string

Employee base rate frequency used with payType Hourly. Common values are Hour, Week. Default is Hour.
Max length: 10

salary

number

Employee gross salary per pay period used with payType Salary.
Decimal (12,2)

primaryStateTax

object

Add or update primary state tax code, amount type (taxCalculationCode), amount or percentage, filing status, exemptions, and supplemental check (specialCheckCalc) information. Only one primary state is allowed. Sending an updated primary state will replace the current primary state.

amount

number

State tax code.
Max length: 50

exemptions

number

State tax exemptions value.
Decimal (12,2)

exemptions2

number

State tax exemptions 2 value.
Decimal (12,2)

filingStatus

string

Employee state tax filing status. Common values are S (Single), M (Married).
Max length: 50

percentage

number

State Tax percentage.
Decimal (12,2)

specialCheckCalc

string

Supplemental check calculation code. Common values are Blocked (Taxes blocked on Supplemental checks), Supp (Use supplemental Tax Rate-Code).
Max length: 10

taxCalculationCode

string

Tax calculation code. Common values are F (Flat), P (Percentage), FDFP (Flat Dollar Amount plus Fixed Percentage).
Max length: 10

taxCode

string

State tax code.
Max length: 50

priorLastName

string

Prior last name if applicable.
Max length: 40

salutation

string

Employee preferred salutation.
Max length: 10

ssn

string

Employee social security number. Leave it blank if valid social security number not available.
Max length: 11

status

object

Add or update employee status, change reason, effective date, and adjusted seniority date. Note that companies that are still in Implementation cannot hire future employees.

adjustedSeniorityDate

string

Adjusted seniority date. Common formats include MM-DD-CCYY, CCYY-MM-DD.

changeReason

string

Employee status change reason. Must match Company setup.
Max length: 15

effectiveDate

string

Common formats include MM-DD-CCYY, CCYY-MM-DD.

employeeStatus

string

Employee current work status. Common values are A (Active), L (Leave of Absence), T (Terminated).
Max length: 20

hireDate

string

Employee hired date. Updates to hire date are not allowed and will be ignored. Common formats include MM-DD-CCYY, CCYY-MM-DD.

isEligibleForRehire

boolean

Indicates if employee eligible for rehire.

reHireDate

string

Rehire date if employee is rehired. Updates to re-hire date are not allowed and will be ignored. Common formats are MM-DD-CCYY, CCYY-MM-DD.

suffix

string

Employee name suffix. Common values are Jr, Sr, II.
Max length: 30

taxSetup

object

Add tax form, 1099 exempt reasons and notes, and 943 agricultural employee information. Once the employee receives wages, this information cannot be updated. Add or update SUI tax state, retirement plan, and statutory information.

fitwExemptNotes

string

Notes for FITW exemption.
Max length: 250

fitwExemptReason

string

Reason code for FITW exemption. Common values are SE (Statutory employee), CR (clergy/Religious).
Max length: 30

futaExemptNotes

string

Notes for FUTA exemption.
Max length: 250

futaExemptReason

string

Reason code for FUTA exemption. Common values are 501 (5019c)(3) Organization), IC (Independent Contractor).
Max length: 30

isEmployee943

boolean

Indicates if employee in agriculture or farming.

isPension

boolean

Indicates if employee is eligible for pension.

isStatutory

boolean

Indicates if employee is statutory.

medExemptNotes

string

Notes for Medicare exemption.
Max length: 250

medExemptReason

string

Reason code for Medicare exemption. Common values are 501 (5019c)(3) Organization), IC (Independent Contractor).
Max length: 30

sitwExemptNotes

string

Notes for SITW exemption.
Max length: 250

sitwExemptReason

string

Reason code for SITW exemption. Common values are SE (Statutory employee), CR (clergy/Religious).
Max length: 30

ssExemptNotes

string

Notes for Social Security exemption.
Max length: 250

ssExemptReason

string

Reason code for Social Security exemption. Common values are SE (Statutory employee), CR (clergy/Religious).
Max length: 30

suiExemptNotes

string

Notes for SUI exemption.
Max length: 250

suiExemptReason

string

Reason code for SUI exemption. Common values are SE (Statutory employee), CR (clergy/Religious).
Max length: 30

suiState

string

Employee SUI (State Unemployment Insurance) state.
Max length: 2

taxDistributionCode1099R

string

Employee 1099R distribution code. Common values are 7 (Normal Distribution), F (Charitable Gift Annuity).
Max length: 1

taxForm

string

Employee tax form for reporting income. Valid values are W2, 1099M, 1099R. Default is W2.
Max length: 15

veteranDescription

string

Indicates if employee is a veteran.

webTime

object

Add or update Web Time badge number and charge rate and synchronize Web Pay and Web Time employee data.

badgeNumber

string

Badge number usually issued for time and attendance system use.
Max length: 50

chargeRate

number

Rate to be charged to third party for time worked by the employee. It is most commonly referenced in the Cost Center Charge, Cost Center Charge vs. Cost Reports, and the Customer Invoice time and attendance reports.
Decimal (12,2)

isTimeLaborEnabled

boolean

If set to true, changes to employee data will be reflected in Web Time.

workAddress

object

Add or update employee's work address, phone numbers, and email. Work Location drop down field is not included.

address1

string

1st address line.
Max length: 40

address2

string

2nd address line.
Max length: 40

city

string

City.
Max length: 40

country

string

Country.
Max length: 30

county

string

County.
Max length: 30

emailAddress

string

Email.
Max length: 50

location

string

Work Location name.
Max length: 50

mailStop

string

Employee mail stop.
Max length: 10

mobilePhone

string

Mobile phone number.
Max length: 12

pager

string

Employee pager number.
Max length: 20

phone

string

Phone number.
Max length: 12

phoneExtension

string

Phone number extension.
Max length: 10

postalCode

string

Postal code.
Max length: 10

state

string

State or province.
Max length: 2

workEligibility

object

Add or update I-9 work authorization information.

alienOrAdmissionDocumentNumber

string

Employee USCIS or Admission Number.
Must be 7-10 characters and may begin with an 'A'

attestedDate

string

The date the I-9 Verification form was attested by Employer or Authorized representative. Common formats are MM-DD-CCYY, CCYY-MM-DD.

countryOfIssuance

string

If Foreign Passport number is provided, provide its country of issuance. Must match Paylocity setup.
Max length: 30

foreignPassportNumber

string

Foreign Passport Number.
Max length: 50

i94AdmissionNumber

string

Form I-94 admission number.
Must be 11 numeric characters

i9DateVerified

string

Common formats include MM-DD-CCYY, CCYY-MM-DD.

i9Notes

string

Notes regarding employee's i9.
Max length: 4000

isI9Verified

boolean

Indicates if employee I9 is verified.

isSsnVerified

boolean

Indicates if employee SSN is verified.

ssnDateVerified

string

The date of employer verification of employee SSN. Common formats include MM-DD-CCYY, CCYY-MM-DD.

ssnNotes

string

Notes regarding employee's SSN.
Max length: 4000

visaType

string

Employee Visa type. Must match one of the system coded values.
Max length: 100

workAuthorization

string

Employee work authorization. Must match one of the system coded values.
Max length: 100

workUntil

string

End date of employee work eligibility. Common formats include MM-DD-CCYY, CCYY-MM-DD.

401

Unauthorized

403

Forbidden

429

Too Many Requests

Language

Credentials

OAuth2


xxxxxxxxxx
1
curl --request GET \
2
     --url https://apisandbox.paylocity.com/api/v2/companies/companyId/employees/employeeId \
3
     --header 'accept: application/json'


xxxxxxxxxx
286
}
1
{
2
  "additionalDirectDeposit": [
3
    {
4
      "accountNumber": "string",
5
      "accountType": "string",
6
      "amount": 0,
7
      "amountType": "string",
8
      "blockSpecial": true,
9
      "isSkipPreNote": true,
10
      "nameOnAccount": "string",
11
      "preNoteDate": "string",
12
      "routingNumber": "string"
13
    }
14
  ],
15
  "additionalRate": [
16
    {
17
      "changeReason": "string",
18
      "costCenter1": "string",
19
      "costCenter2": "string",
20
      "costCenter3": "string",
21
      "effectiveDate": "string",
22
      "endCheckDate": "string",
23
      "job": "string",
24
      "rate": 0,
25
      "rateCode": "string",

200Successfully Retrieved

404The employee does not exist

500Internal Server Error