Enable your customers to log in to their admin payroll account by embedding Pinwheel Link modal into your apps.

To implement Company Connect in your app using the Link modal, complete the following prerequisites:

• Your app must register users and associate Company Connect data with users' data.
• Create a company connection and link token before opening the link modal.
  • The id of the Company Connection must be stored with the user so that when they return 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 collects the data. After the data is available, Pinwheel sends webhook events and uses the Company Connect API to retrieve the data.

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. It matters because to create a Company Connection, you give it the name of the user's company, and if you don't know it ahead of time, you must 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, manually using the Developer Dashboard, or programmatically, when registering the user (see below for how to do this). In either case, you must associate the id of the Company Connection with the registered user, and retrieve it when they login to the app. The company_connection_id is required in Step 2: Create the link token.

If you still need to know who your users are, you must create the Company Connection as part of the flow of the app.

Get the company_name

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

• Ask for it. It is the recommended approach, as it's unlikely any serious potential customer is 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 is the preferred approach.

Create the company connection programmatically

Once you have the company_name, you can call the Create Company Connection endpoint. The response contains the company_connection_id required to create the link token.

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, the app knows which company connection to use.

Step 2: Create the link token

Create Link Token by sending the POST request to the link_tokens endpoint.

In the following request payload, you can see the fields that are required to create a link token for use with Company Connect:

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

• org_name: The name of your organization.
• required_jobs: The jobs run to get census, employment, and income data. At least one of these jobs is required. The possible values are company_census, company_incomes, and company_employments. The impact of including one or more of these jobs is to limit payroll platform search results on the platforms that support the jobs you specify. Most payroll platforms that support Company Connect jobs support all these three jobs.
• company_connection_id: The ID of the company connection.
• language - The language that the link modal uses.

The response to this call returns a link token you can use to launch the Link Modal in your app. See Link modal for details.

Leverage the Company Connect test console

On the Company Connect page of your Developer Dashboard, Pinwheel offers the Company Connect test console to help you test link token creation. This developer tool allows you to select an existing Company Connection created in sandbox, development, or production modes and generate a link token. After the link token is created, you can open the Link Modal and connect to a payroll platform, which then collects data and sends webhooks as described above.

Also, when you select the Show Request JSON checkbox, the console displays helpful information that can be used to structure link token requests in your code.

Step 3: 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 Pinwheel Link documentation for best practices on how to set up the Link modal and show it to your users.

After your customer logs in to their payroll platform using the Link Modal, you start receiving webhook events indicating signal data is available to retrieve using Company Connect API endpoints.

📘

Are you looking to use Pinwheel's Company Connect Landing Page instead of using the link modal? Check out Company Connect Landing Page.