GuidesAPI ReferenceChangelog
Log In
Guides

Supplement Shifts with T&A Platforms

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, Timesheets.com, 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.

12510

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

{
    "account_id": "0f45b178-82ff-45fb-93e4-49d01249aa1a", // UUID
    "additional_platforms": [
        {
            "platform_type": "time_and_attendance", // time_and_attendance
            "end_user_id": "my_user_12345", // user ID you provide when creating the Link token
            "action": "login", // none | login | search | ask,
            "platform_id": "7ceec993-c958-4b90-b419-fda2506b612d" // Optional<UUID> if action is login
        }
    ]
}

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).

7734

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.

11252

action: search

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

12510

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.

13394

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.