GuidesAPI ReferenceChangelog
Log In
Hey! These docs are for version 2021-07-28, which is no longer officially supported. Click here for the latest version, 2023-11-22!

# Introduction

Users can connect their payroll accounts to share income and employment data with your application. After a user connects their payroll account, several jobs are asynchronously executed in the background to retrieve data from their account and make it available to your application through Pinwheel's REST API.

**`employment`**Employment information about the user such as their employer's name, employment status, and start date. See the full API reference [here](🔗).
**`identity`**Personally identifiable information about the user such as their full name, date of birth, and the last 4 digits of their SSN. See the full API reference [here](🔗).
**`income`**Income information about the user such as their annual salary or hourly wage. See the full API reference [here](🔗).
**`paystubs`**The user's most recent and historical paystub data. It includes gross pay, net pay, and more detailed information such as deductions and taxes. See the full API reference [here](🔗).
**`shifts`**Ongoing and completed work performed by a user. It includes details about shift dates, timestamps, the type of work, and associated earnings. See the full API reference [here](🔗).

# Implementation

## Step 1: Subscribe to Webhook Events

Pinwheel executes jobs in the background, so the best way to be notified when data is available is to subscribe to [webhooks](🔗). As a user's account is connected and data is collected, events are posted to your webhook to alert your app that the data is ready for consumption. Webhook events can be customized to your use case, so subscribe to the jobs your application requires. The `account.added` [webhooks](🔗) signals a user's account has been connected, and the rest of the webhooks are job specific.

The complete guide to webhooks can be found [here](🔗).

## Step 2: Create a Link token

Create a Link token specifying the jobs that your application requires using the `required_jobs` parameter.

The response includes a short-lived `token` that expires after 15 minutes and a unique `id`. Persist the `id` in your database.

## Step 3: Initialize Link

Using the Link token that was created, open the Link modal in your client application. In addition to passing in the token, you can optionally pass in several callback handlers.

Calling `` renders the Link modal in full screen mode.

## Step 4: Responding to Webhook Events

The `account.added` webhook event is published after a user logs in to their payroll account. Using the `link_token_id` you persisted earlier, you can associate the account with the user who logged in with Link.

Subsequent webhook events are published when data for a job is available. For example, the `employment.added` event is sent once employment data is ready.

For accounts with a lot of data, gathering every available shift and paystub can take quite some time. To communicate this progress, both the `paystubs.added` and `shifts.added` webhook events have a `payload.parms.sync_status` field letting you know when Pinwheel is done syncing data from your user's payroll platform. A status of `in_progress` means we are still collecting data, while a status of `complete` mean we are done.

If you would instead prefer to be notified after specific days of data have been synced, you can subscribe to any of the sync status events which fire as soon as the relevant data has been retrieved. The sync status events are:

  • `paystubs.seven_days_synced`: Triggered when 7 days of paystubs have been collected

  • `paystubs.thirty_days_synced`: Triggered when 30 days of paystubs have been collected

  • `paystubs.ninety_days_synced`: Triggered when 90 days of paystubs have been collected

  • `paystubs.fully_synced`: Triggered when all available paystubs have been collected

You can use these sync events to fit your use case. E.g, if you only require a single paystub, you can subscribe to `paystubs.seven_days_synced`. This event will trigger once 7 days has elapsed from the first observed paystub, i.e. you will be notified as soon as the first paystub is available. Similarly, you would subscribe to the `paystubs.thirty_days_synced` event if you need at least 2 paystubs.

For Shifts, follow the same convention but swap out the prefix, e.g., `shifts.seven_days_synced`.

Occasionally there might be a delay until the data is available. In these cases, we send a webhook with a `pending` outcome. This indicates that a job was unable to be completed on its first attempt and will be retried up to 24 hours after the initial attempt. A job with a `pending` outcome will transition to either an `error` or a `success` within the 24 hour window and you will be notified via webhook.

## Step 5: Retrieving Income and Employment Data

Upon receiving the relevant webhook events, you will make API requests to retrieve data from the different Income and Employment endpoints.

### Employment



See the full Employment API reference [here](🔗).

### Paystubs



See the full Paystubs API reference [here](🔗).

### Income



See the full Income API reference [here](🔗).

### Identity



See the full Identity API reference [here](🔗).

### Shifts



See the full Shifts API reference [here](🔗).

## Step 6 (Optional): Query for Job Results

If your application never subscribed to webhook events, or your application server failed to handle the webhook events, you can query the Jobs endpoint with the ID of the Link token used to initialize Link to fetch the results.



Please contact [[email protected]](🔗) for access to our [Developer Dashboard](🔗).