This guide describes how to enable your customers to log in to their admin payroll account by embedding our Link modal into your own apps.

Looking to use our Company Connect Landing Page instead? Check out Company Connect Landing Page.

Company Connect App Overview

To implement Company Connect in your app using the Link modal, the following basic flow is required:

• Your app must register users and be able to associate Company Connect data with your user data.
• A Company Connection and Link token must be created prior to opening the link modal.
  • The id of the Company Connection must be stored with the user, so that when the user returns to your app, they can re-use the Company Connection.
• The app opens the Link modal, and your customer interacts with it to log into their admin account.

Once the user successfully connects to their admin payroll account, Pinwheel will collect the data. Once the data is available, Pinwheel will send webhook events and the data can be retrieved using the Company Connect API.

Step 1: Create the Company Connection

Depending on how you design and market your app, you may know who your users are and what company they work for, or you might not. This matters, because to create a Company Connection, you'll give it the name of the user's company and if you don't know it ahead of time, you'll need to get it one way or another within the app.

If you're only providing your app to users you know about, one possibility is to create the Company Connection in advance, either manually using the Developer Dashboard, or programmatically, when you register the user (see below for how to do this). In either case, you'll need to associate the id of the Company Connection with the registered user, and retrieve it when they log in to the app. The company_connection_id is needed for Step 2, below.

If you don't already know who your users are, you'll need to create the Company Connection as part of the flow of the app.

Getting the company_name

If you don't already know the company your user works for, you have a couple options:

• Ask for it. This is the recommended approach, as it's unlikely any serious potential customer will be unwilling to provide it, or get this wrong.
• Derive it from the user's email, if you have it.
  • Although it's unlikely, the user could provide a personal email, or the user could be a consultant with a different email address, so asking for the company name directly is preferred.

Creating the Company Connection programmatically

Once you have the company_name, you can POST to the Company Connection creation endpoint. The response will contain the id of the connection.

Be sure to store the company_connection_id with the user's data, so that if the user needs to log in to the account again in the future, the app knows which company connection to use.

Step 2: Create the Link Token

Use our Create Link Token API to create a Link token that you will use for the following steps.

Your link token payload will look something like this:

{
   "org_name": "<Your company name>",
    "required_jobs": [
      "company_incomes"
    ],
    "company_connect": {
      "company_connection_id": "<Company Connection ID>"
    },
    "language": "en"
}

The response of this call will return a link token you can use to launch the Link modal in your app.

Step 3: Use the Link token to Open the Link modal

With your newly created Link token, use the Link modal inside your app to prompt customers to connect their payroll providers. You can reference our Link documentation for best practices on how to set up the Link modal and show it to your users.

Once your customer logs in to their payroll platform using the Link Modal, you will begin receiving webhook events that signal data is available to be retrieved using Company Connect API endpoints.