GuidesAPI ReferenceChangelog
Log In

While many companies have time and attendance (T&A) data available via their payroll platform, some companies record employee shifts data in a separate system. To account for this, we've built out coverage for the major T&A platforms, such as Humanity,, When I work, Deputy, Homebase, and many more.

A successful [earned wage access](🔗) implementation requires both paystubs and shifts data. Payroll accounts contain shifts data around 1/3rd of the time. You can maximize shifts coverage by helping users connect both their payroll and T&A accounts.

# Example User Experience

Here’s an example application flow for an earned wage access experience. This flow showcases a user with payroll data in one account and shifts data in a separate T&A account. This flow corresponds to the **action: search** variant in Step 3 of this guide.


# Implementation

First, you'll ask the user to connect a payroll account. Once the user successfully connects their payroll account, Pinwheel will analyze the payroll data and send you a webhook event recommending if a T&A account could supplement shifts coverage. Based on the recommendation, you will ask the user to connect a separate T&A account. Finally, you'll pull payroll and shifts data from the connected accounts.

_Here's the process in detail:_

## Step 1: Connect payroll account

### If you built your own search

Filter your platform and employer search experience to only show results where at least `paystubs` is in the `supported_jobs` attribute. Do not filter results based on `shifts` support at this point in the flow, since you'll require `shifts` in Step 3.

Once the user selects an employer or platform, create a [Link token](🔗) with `platform_type` set to `payroll` and the `platform_id` or `employer_id` that the user selected during search.

### If you use Pinwheel Link's search

Create a [Link token](🔗) with `platform_type` set to `payroll` and `paystubs` in the `required_jobs`. Link excludes platforms and employers from the search results that don't support everything in `required_jobs`. Therefore, do not include `shifts` in the `required_jobs` as it will be required in step 3.

## Step 2: Determine if a T&A account is needed

Listen for the `account.additional_connections_recommended` webhook event. This event evaluates the data retrieved from the payroll account to determine if a T&A account could provide additional data. To make this determination, we look at:

  • Type of compensation (e.g., salaried workers don’t need `shifts` data)

  • Availability of shifts data (e.g., the payroll account may already have `shifts` data)

  • Which platforms the employer uses (e.g., Tin Pan Creamery uses 7Shifts)

_Example `account.additional_connections_recommended` webhook event_

## Step 3: Connect T&A account if needed

This `account.additional_connections_recommended` webhook event will recommend different actions for the `time_and_attendance` platform_type in the `action` attribute.

### action: none

Take the user to the next part of your app experience. No more Pinwheel interactions are required because the payroll account contained all the expected information (e.g., the user is salaried or they are hourly and shifts data is available).


### action: login

If the `account.additional_connections_recommended` webhook included a `platform_id`, you don’t need to show a search screen to the user. We have a known mapping between the user’s employer and a specific T&A platform. Create a [Link token](🔗) with `platform_type` set to `time_and_attendance` and `platform_id` set to the `platform_id` in the `account.additional_connections_recommended` event payload.


### action: search

We believe the user may have a T&A platform separate from their payroll platform, but we don’t know which one.


**If you implemented your own search**

If no `platform_id` is included in the webhook event, show users a search screen for platforms where the attribute `platform_type` is set to `time_and_attendance`. Once the user selects a T&A platform, create a [Link token](🔗) with `platform_type` set to `time_and_attendance` and `platform_id` or `employer_id` set to the user’s selection.

**If you use Link’s search**

Create a [Link token](🔗) with `platform_type` set to `time_and_attendance`. If a `platform_id` is provided by the `account.additional_ connections_recommended` webhook event, set `platform_id` in the Link token. `shifts` should be the only job in the `required_jobs` list.

### action: ask

You will want to ask the user if they record their hours worked in their payroll provider or in another system. If they say they record their hours in another system, launch the “action: search” experience.

**action: ask** is sent because we can’t find sufficient `shifts` and `paystubs` data from the payroll account. Therefore, we’re unsure if the lack of `shifts` data is because the information is stored elsewhere, or because the user is inactive, or because they are salaried instead of hourly.


## Step 4: Retrieve data

You will receive webhook events for the 1 or 2 accounts the user connected. We will send webhook events for all of the platform's supported jobs, not only what's listed in `required_jobs`.

Retrieve any relevant data from the accounts using the [Income and Employment endpoints](🔗). You will get account IDs from the `account.added` webhook events. The T&A account will have a unique account ID from the payroll account. However, you will only be billed for one account.