Add new employee

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

New Employee API sends new employee data directly to Paylocity Payroll/HR solution. Companies who use the New Hire Template in Paylocity Payroll/HR solution may require additional fields when hiring employees. New Employee API Requests will honor these required fields.

Path Params

companyId

string

required

The Paylocity Company Identifier. This is the unique value provided by Paylocity to each specific Payroll Entity.
Allowable Values:
9 char max

Body Params

Employee Model

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

additionalRate

array of objects

Add Additional Rates.

additionalRate

benefitSetup

object

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

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

customDateFields

array of objects

length ≤ 8

Up to 8 custom fields of the date type value.

customDateFields

customDropDownFields

array of objects

length ≤ 8

Up to 8 custom fields of the dropdown type value.

customDropDownFields

customNumberFields

array of objects

length ≤ 8

Up to 8 custom fields of numeric type value.

customNumberFields

customTextFields

array of objects

length ≤ 8

Up to 8 custom fields of text type value.

customTextFields

departmentPosition

object

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

disabilityDescription

string

Indicates if employee has disability status.

emergencyContacts

array of objects

Add or update Emergency Contacts.

emergencyContacts

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

workAddress

object

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

workEligibility

object

Add or update I-9 work authorization information.

Responses

401

Unauthorized

403

Forbidden

429

Too Many Requests

Language

Credentials

OAuth2


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


xxxxxxxxxx
 
1
[
2
  {
3
    "employeeId": "string"
4
  }
5
]

201Successfully added

400Bad Request

500Internal Server Error