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.
This section requires that you set your employees' details for proper onboarding into the payroll system.
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.
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.
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.
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.
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.
- 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.
An alphanumeric field where you set your employee's work email address.
Depending on your employee's role, you can give your employee Admin access or Employee access. You can read more about User Access Types.
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
- 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.
In the contract section, you set your employee's compensation terms.
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.
Your employee's work schedule could be any of the following options depending on their contract.
|You select this option if your employee works the minimum number of hours you have defined for their work.
|You select this option if an employee works less than your organization's standard work period. They usually work fewer hours than a full-time employee.
|You select this option if you are onboarding the employee for a limited period where they have a pre-determined termination date.
|You select this option if the employee is on a professional learning experience with your company.
|You select this option if the employee works for you at certain times of the year to meet your organizational needs.
The compensation type determines the compensation amount that your employee receives. You can set the following compensation types for your employees:
|You select this option if your employees receive a fixed payment amount for the service they render at your company. Selecting this option requires setting a fixed compensable amount for the employee.
|You select this option if you pay your employee based on the number of hours they work. When you choose this option, you need to set the Hourly rate for the employee.
|You select this option if you pay your employees based on the number of units they perform. Selecting this option means you need to set the Unit Work rate for the employee.
|You select this option if you pay your employee based on the revenue they bring into your company. You set a fixed compensable amount if you choose this option.
|You select this option if you pay a non-employee like a freelancer, an independent contractor, or a professional who provides services. Selecting this option requires you to set a fixed compensable amount.
|Owner Draws 1099
|You select this option if the owner of your company takes money out of the company for personal use.
|You select this option if you pay an employee a substantial portion of their compensation from tips. Selecting this option requires you to set a pay rate.
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.
Depending on the compensation type agreed upon with the employee, this field varies into different options.
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.
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.
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.
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.
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.
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.
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.
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.
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.
If your employee prefers this payment method, your company sends a check for their salary or wage to their residential address provided during onboarding.
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.
Updated 7 months ago