Introduction

Income, Employment, Identity, Paystubs, and Shifts (I&E) Monitoring alerts you to changes in a user's information, such as if they're still actively employed or if their compensation has changed.

After a user logs into their payroll account through Link, Pinwheel establishes a persistent connection to the payroll provider. We'll pull income, employment, identity, paystubs, and shifts data from this connection daily and proactively notify you of any changes.

Implementation

Step 1: Enable I&E Monitoring on Your Workspace

Please contact Pinwheel support so we can enable I&E Monitoring for your workspace. Once enabled, Pinwheel will automatically monitor data changes for any supported accounts.

Step 2: Subscribe to I&E Webhook Events

The income.added, employment.added, identity.added, paystubs.added, and shifts.added webhook events will be sent whenever new data is available for a payroll account. We currently ignore changes to whitespacing and character casing.

You can register a webhook endpoint for these events as described in Subscribing to Webhook Events.

Step 3: Retrieve I&E Data

Using account_id from the *.added webhook event, make a request to the appropriate endpoint to get the latest data for the account. In the response, the field data.updated_at is a timestamp of when the data last changed. The field meta.refreshed_at is a timestamp of when the payroll provider was last queried for changes.

The paystubs.added and shifts.added webhook event will include two properties, added and deleted, which are lists of paystub or shifts record IDs that have been added or deleted, respectively. Paystub and shift records are immutable, so any revisions are treated as deletions and additions.

Pinwheel always returns a snapshot of the latest account data. To track these changes over time, you can store snapshots from Pinwheel when you receive them.

Step 4: Maintain Account Monitoring

Accounts can no longer be monitored due to various events such as session expiration, user settings changes, and platform updates. Pinwheel will send an account.monitoring_status.updated webhook event if our ability to monitor an account changes. To reconnect the account for I&E Monitoring, you should have the user re-authenticate via Link. We retrieve new data immediately after users reestablish account monitoring so you can provide updated information to users quickly.

Subscribe to Account Monitoring Status Webhook Events

The monitoring_status field in the account.added webhook event will indicate if a payroll account supports the ongoing integration for I&E Monitoring.

The account.monitoring_status.updated webhook event will be sent if this state changes. For example, the user_action_required value indicates that an account requires On Demand Updates to be triggered to re-establish monitoring.

You can register a webhook endpoint for these events as described in Subscribing to Webhook Events.

Re-Establish Monitoring

We're unable to retrieve data for an account that requires user action until the user has gone through Link again to reestablish monitoring.

You can initiate this user re-authentication flow in Link by creating a Link Token with the account_id field set. You should also provide org_name to personalize the Link flow for your brand. For example:

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "account_id": "account_id of the account to reestablish monitoring for"
}

Once launched, Link will ask the user for the minimal amount of information necessary to reestablish monitoring. For example, if the user only needs to complete multi-factor authentication, we will drop them directly into that portion of the flow.

You can also set skip_intro_screen: true to disable the introductory screen shown in Link. See Customization in the Implementation Guide for more info.

You'll get an onLogin callback and receive an account.monitoring_status.updated webhook event when monitoring is successfully reestablished. We'll immediately trigger data refresh jobs once the login completes to get you the latest account data.

Extensions

Disable Monitoring for Individual Accounts

If you'd like to selectively disable all Monitoring for an individual account, use Disable Monitoring. Calling this will send an account.monitoring_status.updated webhook event with current_monitoring_status set to customer_disabled.

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