Create Employee

After creating your company on our API, the next entity you must create is the Create Employee entity. However, calling this endpoint, as seen here, needs a complex information structure. The API requires you to set some of these pieces of information at the onset, while you can update others later. The required information is essential for your Payroll calculation and must be appropriately filled.

📘

Updating employee information

Sometimes, company admins don't have all the information about employees needed for payroll calculation. You can let the employees add their information via the Update endpoint.

Personal Information

This section requires that you set your employees' details for proper onboarding into the payroll system.

First Name

You set this field to be your employees' legal first name. You can only input alphanumeric characters here with a minimum character count of 1 and a maximum character count of 35 for validation purposes.

Last Name

This field also contains only alphanumeric characters and, similarly, has a minimum character count of 1 and a maximum character count of 35. You set your employees' legal last name here.

Date of Birth

This field receives a minimum value of 120 years before the set date and a maximum value of the day before the set date. You set your employees' legal birth date here.

Employee Identification

Here, you can determine if your employee is a Full Employee or a Contractor. You hire full-time employees without an end date in mind, and they have full access to the company's resources, while you hire a contractor to work for a shorter period on a particular project. Onboard your employees based on how and why you employed them.

SSN/FEIN

The Social Security Number (SSN) or Federal Employer Identification Number (FEIN) is a 9-character number issued by the government for legal identification purposes. Employees' SSNs enter this field, while contractors fill their FEIN here.

📘

W2 and 1099 tax forms

In the tax setups of employees, please note that their SSN or FEIN is necessary. You set up employees' W-2 tax forms with their SSNs, while you use contractors' FEIN to file their 1099 tax forms.

You cannot view the SSN or FEIN of an employee or contractor after creation or updating for privacy reasons. Changing SSN/FEIN is a nonstandard operation that our API does not support. As a result, you must contact our support to do so because a couple of validation rules need to be fulfilled.

🚧

Valid SSN

SSN cannot:

• begin with "9" as the first digit
• have "666" as digits 1, 2 and 3
• have "000" as digits 1, 2 and 3
• have "00" as digits 4 and 5
• have "0000" as digits 6, 7, 8 and 9

These are recommended but not required rules, as you can sometimes come across real SSNs which will not follow these rules.

Email

An alphanumeric field where you set your employee's work email address.

Access Type

Depending on your employee's role, you can give your employee Admin access or Employee access. You can read more about User Access Types.

Residential Address

An employee's residential address is used for tax setup and payroll calculations. Our API requires you to set your employee's valid address, which includes the following:

• Address Lines
• City
• State
• Zip code

Just as with your company or work location, your employee's residential address must be tax valid as it is essential for your payroll calculation. You can use geo-location to be sure about the employee's address.

Contract

In the contract section, you set your employee's compensation terms.

Start Date

You set the date when your employee starts working with your company in this section. The start date takes values from 50 years before the set date to 5 years after the set date for validation purposes.

Work Schedule

Your employee's work schedule could be any of the following options depending on their contract.

Compensation Type

The compensation type determines the compensation amount that your employee receives. You can set the following compensation types for your employees:

Compensation Hours

Employee hours per pay period also have a different meaning depending on the Compensation Type value.

In a simple situation like the Hourly or Tipped compensation type where compensation hours mean standard work hours per pay period, you can change hours later based on actual worked hours. You can only set the minimum number of hours an employee can work to 0 and the maximum to 250 hours for validation purposes.

Although it looks illogical, the system requires this information even if the Compensation Type field is not set to Hourly or Tipped because it is essential information for calculating data for ACA/Cobra reporting.

If the company does not process these reports (the company has less than a certain number of employees), and if the Compensation Type field is not set to Hourly or Tipped, you can set this field to zero.

However, suppose you initially set your company's compensation hours to zero but eventually grow over the ACA/Cobra reporting limits. In that case, you must update all employees' contracts and put their proper value.

Compensation amount

Depending on the compensation type agreed upon with the employee, this field varies into different options.

Hourly rate

When you set the Compensation Type field to Hourly or Tipped, you should fill the Compensation Amount field with the Hourly Rate. This rate will be prefilled in the payroll run and will be used to calculate employee wages together with compensation hours. For validation processes, this field takes values from 0 and has a maximum value of 1000.

Compensable amount

When the Compensation Type field is set to Salaried, Commissioned, Form 1099 or Owner Draws 1099, you should set the Compensation Amount field with the Compensable Amount. This amount will be prefilled in the Payroll Run as a wage for the employee. This field takes values from 0 and a maximum of 1000000 for validation purposes.

Unit Work rate

When you set the Compensation Type field to Piecework, you set the Amount field to Unit Work Rate. The system adds a field of Compensation Number of Units, which takes a value from 0 and a maximum value of 1000000.

This rate will be prefilled in the Payroll Run and, together with the Number of Units, will be used to calculate employee wage. The field takes a value from 0 and has a maximum value of 1000000 for validation purposes.

❗️

Contract Termination

In case you want to terminate an employee's contract, you can call the terminate employee endpoint here to remove the employee's details from the payroll run.

Position Details

Work Location

You can set an employee to Work from Home or your company's Work location. Creating your company's work location during the company onboarding is an essential aspect of your company setup as it links your employees and where they work.

Statutory Employee

You check the statutory employee checkbox if you regard your independent contractor as an employee for tax withholding purposes. The independent contractor must have met specific criteria to be considered a Statutory Employee. You should send your statutory employee the W2 tax form instead of the 1099-MISC one.

943 Agricultural Employee

You check this box if you report taxes withheld from your agricultural employees' salary if they meet specific criteria for the tax withholding. Do not check this box if your employees are not farmworkers or do not meet the wage criteria to file Form 943.

Pay Method

Depending on the preferred choice of your employee, you can choose between the two options for the employee's payment method. You can pay your employees by check, direct deposit, or both.

Direct Deposit

This payment method requires the employees to provide their bank details, including their:

• Account number- For validation purposes, the field takes a minimum character count of 4 and a maximum of 20.
• Account Holder Name- For validation purposes, the field takes alphanumeric characters with a minimum of 1 character and a maximum of 50.
• Account Type- You can select Savings or Checkings depending on the employee's account type.
• Routing Number- This field takes only nine numeric characters for validation purposes.

Check

If your employee prefers this payment method, your company sends a check for their salary or wage to their residential address provided during onboarding.

📘

Pay Allocation

By default, our system pays the total percentage or amount of your employees' wages to their preferred payment method choice. However, you can update this choice by calling the update employee endpoint.

You can allocate a fixed amount or percentage of the employee's wage to a payment method of their choice via the endpoint.