Technical Implementation
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.
Updated 22 days ago