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.