This guide explains how to implement Company Connect. For an overview of concepts in the Pinwheel system that are referenced in this doc, review the Platform Overview.

Overview

In short, Company Connect works by connecting to your target company's admin payroll account, retrieving employment and income data for the entire company. We notify you that data is ready via webhooks, and provide API endpoints for retrieving the data. We also attempt to retrieve updated data automatically, and when this succeeds, we will send new webhooks to notify you that updated data is available.

To facilitate connection to your customer's data, we offer two options: embed the Link modal in your apps, or lead your customer to log in via our Company Connect Landing Page. See below for details.

Prerequisites

• Access to the Pinwheel API.
• Access to the Developer Dashboard.
• Company Connect enabled for your workspace - contact [email protected] for access.

Step 1: Subscribe to Webhook Events

In order to receive timely notifications of when company data becomes available, we recommend that you subscribe to the following webhook events:

• company_connection.census.added - signals that a directory of the target company's employees is available.
• company_connection.employments.added - signals that information about each employee's job is available.
• company_connection.incomes.added - signals that information about each employee's income is available.

POST /v1/webhooks
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "url": "https://your-domain.com/webhook_endpoint",
  "status": "ACTIVE",
  "enabled_events": [
    "company_connection.census.added",
    "company_connection.employments.added",
    "company_connection.incomes.added"
  ]
}

See Company Connect Webhook Events for webhook payload schemas and example payloads.

Step 2: Create a Company Connection

The connection to your customer's data is called the Company Connection. You are responsible for creating the Company Connection, and then providing your customer with an interface to log in to their admin account using this connection.

We offer two different interfaces for enabling your customer to connect: embed the Link modal in your apps, or lead your customer to log in via our Company Connect Landing Page.

Link Modal & SDK

Our Link modal is the user interface your customer uses to log in to their payroll platform, and it can be easily embedded into your apps to enable connections to your customer's data. Your app will create a Company Connection and Link Token that are used to open the Link Modal. We offer SDKs for iOS, Android, and React Native apps, as well as web apps.

See Using Link for Company Connect for more.

Company Connect Landing Page

If you're not planning to provide your customers with an app, our Company Connect Landing Page gives you a path forward. In short, you create a Company Connection on your developer dashboard, and we provide you with a link to our Company Connect Landing Page to send to the HR admin at your customer's company (who has access to the admin account). When they access the link, they will be taken to the Landing Page and guided through the process of logging into the admin account.

See Company Connect Landing Page for details on how to use this flow.

A Word on Admin Account Permissions

The data surfaced by Company Connect is not guaranteed to be complete for a given company connection. There are two reasons for this:

• Some payroll platforms may not expose all the possible data we're typically able to provide.
• Admin payroll accounts can have varying levels of access and permission. The more access that an admin account has, the more data will be available for your purposes, so if possible, ensure that the admin person who logs in has the appropriate level of access for your business needs.

If your target company's admin person logs in, but it turns out that they don't have enough access, you will need to start over with a new Company Connection and have an admin with the correct permissions log in instead. If this happens, please reach out to your Pinwheel account executive.

Step 3: Respond to Webhook Events

After the customer admin logs into the admin account, Pinwheel retrieves the data. As the data becomes available, Pinwheel will send webhook events to the URL you registered in step 1, specifically the company_connection.census.added, company_connection.employments.added, and company_connection.employments.added events.

See Company Connect Webhook Events for webhook payload schemas and example payloads.

An example webhook event schema:

{
  "event": "company_connection.census.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "company_connection_id": "e1173ac4-cf02-44ca-9a56-3d9d4aea7007",
    "company_name": "Acme",
    "outcome": "success",
    "added": ["12345", "12346", "12347"],
    "updated": [],
    "deleted": [],
  }
}

In the case of an error retrieving the data, error_code and error_type will be populated. See API Errors for more information.

Step 4: Retrieve the Data

Using the company_connection_id attribute sent in the webhook, you can retrieve company data from Company Connect endpoints:

• List Employees retrieve a list of the company's employees and their contact information. Each employee is identified by their employee_external_id, which is the employee ID as reported by their employer.
• List Employments Data retrieve data about each employee's job, including title, start & termination dates, and class code.
• List Employee Incomes retrieve data about each employee's income.

Note: employee_external_id is the ID reported by the customer and is not guaranteed to be unique from one Company Connection to the next.

Handling updates to the data

Pinwheel will try to automatically refresh your Company Connection data on a periodic basis. When this is successful, you will receive the same webhooks when the updated data becomes available.

When a Company Connection is connected for the first time, the first webhooks you will receive will only have data in the added array. However, when webhooks are resent because of refreshed data, the updated and deleted arrays may contain data as well:

• Employee IDs present in the updated array refer to employees that have previously been added, but the data for that record has changed.
• In general, deleted employees should be uncommon. We will only add employee IDs to this array when the given employee disappears from the admin account used by your company connection. This is usually not caused by employees moving to inactive/terminated status - such employees typically remain visible on the payroll platform so that HR can answer questions about former employees. This could happen if an employee is moved to a different part of the company, and the admin account used to create the Company Connection does not have access to that part of the company.

In some instances we will not be able to automatically refresh the data. When this occurs, the status of the Company Connection will eventually move to Reconnect Needed. This status is available on the developer dashboard where you created the Company Connection.

When a manual refresh is required, the target company's HR team member must log in again to their admin account. For some payroll platforms, this may be required for all data refreshes.

Company Connection status

The status of a company connection is displayed in the developer dashboard (see screenshot above). The possible values for the status are:

• Ready to Connect - the Company Connection has just been created, and the admin account has not been connected yet.
• Processing - Connection to the admin account was successful, and we are gathering the data.
• Data Available - All of the data is now available for this connection.
• Connection Failed - The admin person was not able to log in to their admin payroll account.
• Reconnect Needed - Attempts to refresh/update data over the course of a few days have failed, and manual reconnection is necessary.