# Employees

Employee records are added by the company and acted on by the employee. See
[Employees and payroll](/core-data-types/employees) for the data types, the
[Company service](/grpc/partnercompanyingressservice) for employer-initiated calls, and the
[Employee service](/grpc/partneremployeeingressservice) for employee-initiated ones.

## Onboarding

Adds a new employee to a specific company.

See `AddEmployees` ([gRPC](/grpc/partnercompanyingressservice#addemployees) | [REST](/openapi/partnercompanyingressservice/addemployees)) in the API reference.

### AddEmployeeResult

See [AddEmployeeResult](/core-data-types/employees#addemployeeresult) in the core data types.

### AddEmployeeError

See [AddEmployeeError](/core-data-types/employees#addemployeeerror) in the core data types.

### AddEmployeeErrorType

See [AddEmployeeErrorType](/core-data-types/employees#addemployeeerrortype) in the core data types.

This contains information of where employee is in onboarding and if agreements are ready to sign. Note nothing is waiting on the employee finishing onboarding but we encourage if there are unsigned documents you prod the user to sign them.

See `GetEmployeeOnboardingStatus` ([gRPC](/grpc/partneremployeeingressservice#getemployeeonboardingstatus) | [REST](/openapi/partneremployeeingressservice/getemployeeonboardingstatus)) in the API reference.

Nothing downstream waits on the employee finishing onboarding, but unsigned agreements are worth
prompting for. Identity verification runs through the
[Shared service](/grpc/partnersharedingressservice); an SSN collision surfaces as a
`kyc_status` of `MUST_LINK_ACCOUNT`, which the [Single sign-on](/integration-guide/single-sign-on) guide covers.

## Limits

Provides list of available contribution types for the employee to configure contribution percentages for. I.e. if an employer does not enable Roth, then only Traditional would be available for the employee to contribute to.

See `ListContributionTypesAvailableForSetup` ([gRPC](/grpc/partneremployeeingressservice#listcontributiontypesavailableforsetup) | [REST](/openapi/partneremployeeingressservice/listcontributiontypesavailableforsetup)) in the API reference.

Provides the limits based on the employee's company's plan configuration and if the employee has any contributions to date.

See `GetEmployeeSetupLimits` ([gRPC](/grpc/partneremployeeingressservice#getemployeesetuplimits) | [REST](/openapi/partneremployeeingressservice/getemployeesetuplimits)) in the API reference.

Provides estimates that can be used to help a user determine how much to contribute. Please make clear to user these are estimates.

See `GetEmployeeSetupEstimates` ([gRPC](/grpc/partneremployeeingressservice#getemployeesetupestimates) | [REST](/openapi/partneremployeeingressservice/getemployeesetupestimates)) in the API reference.

Annual IRS limits come from `GetAnnualContributionLimits` on the
[Constants service](/grpc/partnerconstantsingressservice), which also supplies the Safe Harbor
and Secure Act 2.0 rates and the retirement projection parameters.

## Employee Account Linking on SSN Collision

We enforce SSN uniqueness in our system over persons; we therefore cannot complete KYC for an employee if there is an SSN collision. If an onboarding employee already has an account in our system, they will need to add that employee to their existing account instead of creating a new one. This must be done before the employee can take any actions that require KYC to be complete, even if making updates via the PartnerAPI.

Employee accounts can be linked as follows:

1. `PartnerEmployeeIngressSystem.getEmployeeOnboardingStatus` will return a `MUST_LINK_ACCOUNT` status for KYC. This indicates that the user must log into their existing Basic Capital account.
2. Fetch an `employee_invite_token` from the `PartnerEmployeeIngressSystem`:


See `GetEmployeeInviteToken` ([gRPC](/grpc/partneremployeeingressservice#getemployeeinvitetoken) | [REST](/openapi/partneremployeeingressservice/getemployeeinvitetoken)) in the API reference.

1. Initiate SSO with query params `employeeInviteToken={token}` and `action=link_account`, as described in [Single sign-on](/integration-guide/single-sign-on#initiate-sso):


```
REDIRECT /oauth/{provider}/sso?employeeInviteToken={token}&action=link_account
```

Note that you do not need to call `GetOrCreateUser` in this case. The `employeeInviteToken` replaces the `inviteToken` you would get from the `GetOrCreateUser` call.

1. The user will be prompted to sign into their account and accept the invitation to add this new employment. We will verify that the user's DOB and SSN match to confirm they are linking the correct account. On success, we will add the employment to the account.