Skip to main content

​
Definition

An employment represents a job associated with a connected payroll account. One account can contain data from more than one employment. A user represents the person sharing information. An account represents their connection to an income source. Employments identify the jobs associated with that connection. For example, a user may have worked for two employers that use the same payroll provider. After an account is connected, paystubs may be available from both employers, even when the identity information only describes one job.

​
Matching records

The employment field is available on Identities, Paystubs, and Payroll Documents. Records with the same employment ID belong to the same employment. Employer names can differ between records for the same job. Use the employment ID to match them: In this example, the identity’s employment status applies to Bob’s Donuts. It should not be applied to the unmatched Suzy’s Cupcakes paystub.
Paystubs and payroll documents can have a null employment when they cannot be matched to an employment. These records can still contain useful information. A shared null value does not mean that records belong to the same employment.
Employment IDs are also used when an account contains only one employment. They are not supported as filters for other data sets, such as Gigs or Shifts.

​
Retrieve all records, then match

Use this approach when you need all available records, including paystubs that are not matched to an employment.
  1. Retrieve identities, paystubs, and payroll documents using the user or account filter. Follow pagination to retrieve all available records.
  2. Store the employment value with each record.
  3. Match records with the same non-null employment ID. Keep unmatched records available for separate review or processing.
You do not need to call the Employments endpoint for this approach.

​
Retrieve records for an employment

Use this approach when you only need records associated with a specific employment.
  1. List employments for the user or account.
  2. Use the returned employment id as the employment filter when listing identities, paystubs, or payroll documents.
Filtering by employment excludes unmatched records. If your application needs the applicant’s full available income history, retrieve all records and match them afterward.
Both approaches use the same data delivery webhooks. An account connection alone does not mean its identities, paystubs, or payroll documents are ready. See the Employments API Reference for the complete object and its fields.

​
Testing

A payroll account may contain paystubs from multiple jobs. Use the custom test user below to test this mixed-employment scenario in Sandbox and retrieve the paystubs for the job associated with the connected account.
  1. Open a Flow in Console with Sandbox mode enabled, or initialize embedded Link with sandbox: true. See Sandbox Testing.
  2. In Link, select an Item that supports mixed employments testing, such as ADP.
  3. Enter username test_1 and the password below. If prompted for a verification code, enter 8081.
Password
After data delivery completes, use your Sandbox API credentials to:
  1. Retrieve the account’s identity information to identify the job and read its employment ID.
  2. Use that ID as the employment filter when listing paystubs. The returned paystubs will have the same employment ID as the identity.
Paystubs from other jobs will have employment: null and are excluded by this filter. To retrieve all of the account’s paystubs, including those from other jobs, query by account instead:
Follow pagination and confirm that your application:
  • Matches paystubs with the same non-null employment ID as the identity.
  • Retains paystubs with employment: null without applying the identity’s employment status to them.
  • Excludes unmatched paystubs only when you intentionally use the employment filter.