GuidesAPI ReferenceChangelog
Log In

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

JobData
**`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](🔗).<br/><br/>Employers sometimes use a separate system than payroll to store shifts data. You can maximize coverage by following [Supplement Shifts with T&A Platforms](🔗).

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

Note: The `end_user_id` is your internal reference to the end user. See [User Model](🔗) for more information.
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 `Pinwheel.open()` 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
**Request**

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

### Paystubs
**Request**

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

### Income
**Request**

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

### Identity
**Request**

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

### Shifts
**Request**

**Response**
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.
**Request**

**Response**


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