Company Connect works by connecting to your target company's admin payroll account and retrieving employment and income data for the entire company. It uses webhooks to notify you that data is ready and provides API endpoints for retrieving it. The system also attempts to retrieve updated data automatically, and when successful, it sends new webhooks to notify you that updated data is available.

Prerequisites

Get access to the Pinwheel API and the Developer Dashboard.
Enable Company Connect in your workspace.

Contact [email protected] to get access.

Step 1: Subscribe to webhook events

Subscribe to the following webhook events to receive instant notifications when company data becomes available.

company_connection.census.added: Notifies you when a directory of the target company's employees is available.
company_connection.employments.added: Notifies you when information about each employee's job is available.
company_connection.incomes.added: Notifies you when information about each employee's income is available.
company_connect.status.updated - Notifies you when the status of the company connection changes. See Company Connection status for more information on status transitions and how they can help your implementation workflows.

Subscribe to these webhook events using Pinwheel's Create Webhook endpoint, as the following example illustrates.

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",
    "company_connect.status.updated"
  ]
}

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 must create a company connection and provide your customers with an interface to log in to their admin account using this connection.

To facilitate connection to your customer’s data, Pinwheel offers two options:

Embed the link modal in your apps: Integrate Pinwheel's Link modal directly into your applications. It is the user interface your customers can use to log in to their payroll platform. You can easily embed it into your apps and create a Company Connection and Link Token to open the Link Modal. See Using Link for Company Connect for more information.
Use Company Connect landing page: Alternatively, you can guide your customers to log in through Pinwheel's Company Connect Landing Page. Create a company connection on the developer dashboard and get a link to the Company Connect Landing Page. Send this link to the HR admin at your customer's company who has access to the admin account. When they access the link, they are taken to the Landing page and guided through the login process into the admin account. See Company Connect Landing Page for details on how to use this flow.

📘
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, reach out to your Pinwheel account executive.

A Word on Admin Account Permissions

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

Some payroll platforms may only expose some of the possible data Pinwheel can typically provide.
Admin payroll accounts can have varying levels of access and permission. The more access an admin account has, the more data is available for your purposes. Ensure that the admin person who logs in has the appropriate level of access_ for your business needs.

Step 3: Respond to webhook events

After the customer admin logs into the admin account, Pinwheel retrieves the data and sends webhook events to the registered URLs (See Step 1: Subscribe to webhook events).

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

An example of 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 case of an error while retrieving the data, error_code and error_type are populated. See API Errors for more information.

Step 4: Retrieve data

Use the company_connection_id attribute sent in the webhook to retrieve company data from Company Connect endpoints:

List Employees API retrieves a list of the company's employees and their contact information. You can identify each employee by their employee_external_id, which is the employee ID reported by their employer.
List Employments Data API retrieves data about each employee's job, including title, start and termination dates, and class code.
List Employee Incomes API retrieves 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.

Handle updates to the data

Pinwheel tries to automatically refresh your Company Connection data periodically. When the refresh is successful, you receive the same webhooks as when the updated data becomes available.

When you make a Company Connection for the first time, the first webhooks you receive only have data in the added array. However, when webhooks are resent because of refreshed data, the updated and deleted arrays can also contain data.

Note that:

Employee IDs in the updated array refers to employee records added earlier whose data has now changed.
Data added to the deleted employees array is an uncommon scenario. Pinwheel only adds employee IDs to the deleted array when the given employee disappears from the admin account used by your company connection. It is usually not caused by employees moving to inactive or terminated status - such employees typically remain visible on the payroll platform so that HR can answer questions about former employees.
The deleted array can have employee IDs if an employee moves to a different part of the company and the admin account used to create the Company Connection does not have access to that part.

In some instances, Pinwheel cannot automatically refresh the data. When this situation occurs, the status of the Company Connection eventually changes 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. Some payroll platforms require the HR members to log in again after all data refreshes.

Status of the Company Connection

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 is created, and the admin account must be connected.
Processing - Connection or reconnection to the admin account was successful, and the system is collecting the data.
Data Available - All data is now available for this connection.
Connection Failed - The admin person could not log in to their admin payroll account.
Reconnect Needed - Attempts to refresh or update data over the last few days have failed, and manual reconnection is necessary.

Status transition

When a company connection's status is updated, Pinwheel sends a company_connect.status.updated webhook. Responding to this webhook may be useful in triggering workflows and potentially sending notifications to app users. For instance, if the status transitions to reconnect_needed, you can notify the admin at your target company that they must log in to their account again to refresh and update the company's data.

Reference this diagram to understand what transitions are possible and what they signify: