> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argyle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Employments

> Match payroll records to the same employment.

## Definition

An employment represents a job associated with a connected payroll account. One account can contain data from more than one employment.

A [user](/overview/data-structure/users) represents the person sharing information. An [account](/overview/data-structure/accounts) 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](/api-reference/identities), [Paystubs](/api-reference/paystubs), and [Payroll Documents](/api-reference/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:

| Record   | Employer                     | `employment`                           |
| -------- | ---------------------------- | -------------------------------------- |
| Identity | Bob's Donuts                 | `0183d52a-d3b2-331d-c753-3662a20e352b` |
| Paystub  | Bob's Donuts Associates, LLC | `0183d52a-d3b2-331d-c753-3662a20e352b` |
| Paystub  | Suzy's Cupcakes              | `null`                                 |

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.

<Note>
  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.
</Note>

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](/api-reference/employments/list-all-employments) for the user or account.
2. Use the returned employment `id` as the `employment` filter when listing identities, paystubs, or payroll documents.

```text theme={}
GET /v2/employments?account=0187c66e-e7e5-811c-b006-2232f00f426a
GET /v2/identities?employment=0183d52a-d3b2-331d-c753-3662a20e352b
GET /v2/paystubs?employment=0183d52a-d3b2-331d-c753-3662a20e352b
GET /v2/payroll-documents?employment=0183d52a-d3b2-331d-c753-3662a20e352b
```

<Note>
  Filtering by employment excludes unmatched records. If your application needs the applicant's full available income history, retrieve all records and match them afterward.
</Note>

Both approaches use the same [data delivery webhooks](/overview/data-delivery). An account connection alone does not mean its identities, paystubs, or payroll documents are ready.

See the [Employments API Reference](/api-reference/employments) for the complete object and its fields.