> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tryfinch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paylocity Onboarding

> Set up your Paylocity Marketplace tile and launch Finch Connect when Finch redirects an employer from the Paylocity Marketplace to your application.

Paylocity connections start in the Paylocity Marketplace. For each application Paylocity approves, Paylocity lists a Marketplace tile named **\<Your application> via Finch**. Finch holds the Paylocity credentials for your tile and handles Paylocity's approval of each employer, so you never call Paylocity or hold Paylocity credentials.

## How the flow works

1. A company administrator requests your tile in the Paylocity Marketplace and selects the companies to share.
2. Paylocity sends the administrator to a Finch landing page. Finch creates a Finch Connect session with Paylocity and the selected companies already set, then redirects the administrator to your application with that session.
3. Your application signs the administrator in and launches Finch Connect with the session.
4. The administrator clicks **Connect**. Finch confirms the request with Paylocity and creates the connection.
5. Your application exchanges the authorization `code` for an access token.

Your part is steps 3 and 5. The onboarding process consists of the following steps:

**[Step 1](#step-1-set-up-your-paylocity-marketplace-tile):** Set up your Paylocity Marketplace tile

**[Step 2](#step-2-handle-the-redirect-from-finch):** Handle the redirect from Finch

**[Step 3](#step-3-launch-finch-connect):** Launch Finch Connect

**[Step 4](#step-4-retrieve-the-access-token):** Retrieve the access token

***

### Step 1: Set up your Paylocity Marketplace tile

Paylocity reviews each application before listing its tile. To start, contact your Developer Success Engineer or [implementation-team@tryfinch.com](mailto:implementation-team@tryfinch.com). Finch coordinates the review with Paylocity and asks you for the copy that describes your application on the tile, plus your contacts for Paylocity's evaluation. You don't need a Paylocity account.

Once Paylocity approves your application, Paylocity publishes your tile and Finch enables Paylocity for your application.

### Step 2: Handle the redirect from Finch

When an administrator arrives from the Paylocity Marketplace, Finch redirects them to the first [redirect URI](https://developer.tryfinch.com/implementation-guide/Connect/Create-Account.md#add-redirect-uris) configured on your application, with these query parameters:

| Parameter | Description |
| - | - |
| `session` | The ID of the Finch Connect session Finch created for the Marketplace request. |
| `idp_redirect` | Always `true`. Indicates that the request started in the Paylocity Marketplace. |

```text Example redirect to your application theme={null}
https://example.com/finch/callback?session=f47ac10b-58cc-4372-a567-0e02b2c3d479&idp_redirect=true
```

Make sure that redirect URI points to a page in your application that handles these parameters, and confirm it with Finch before your tile goes live.

When your application receives a request with `idp_redirect=true`, it should:

1. Sign the administrator in, or let them create an account, so you know which of your customers is connecting. If they aren't one of your customers or aren't a fit for your product, send them to your own intake process instead of launching Finch Connect.
2. Launch Finch Connect with the `session` value within 30 minutes. After that the session expires, and the administrator has to request your tile again from the Marketplace.

> [!NOTE]
>
> Don't call `POST /connect/sessions` for these requests. Use the session Finch passes to your application, since it carries the companies the administrator selected in the Marketplace.

These sessions don't include a `customer_id`. Use the signed-in user to associate the connection with the right customer, or carry that context through the [`state` parameter](https://developer.tryfinch.com/implementation-guide/Connect/Set-Up-Finch-Connect#pass-context-with-the-state-parameter).

### Step 3: Launch Finch Connect

Launch Finch Connect with the `session` value, using either flow described in [Create a Finch Connect Session](https://developer.tryfinch.com/implementation-guide/Connect/Set-Up-Finch-Connect.md#launch-finch-connect).

For the embedded flow, pass the `session` value to `connect.open()`:

```js Embedded flow theme={null}
connect.open({ sessionId: session });
```

For the redirect flow, send the browser to Finch Connect with your `redirect_uri`, which must match one of your application's redirect URIs:

```text Redirect flow theme={null}
https://connect.tryfinch.com/authorize?session=f47ac10b-58cc-4372-a567-0e02b2c3d479&redirect_uri=https://example.com/finch/callback
```

By default, the session requests every product Finch supports for Paylocity. To request fewer in the redirect flow, add `products` as a space-separated list, for example `&products=company%20directory%20individual%20employment`.

In Finch Connect, Paylocity is already selected and the administrator clicks **Connect** to finish. If they shared more than one company in the Marketplace, Finch Connect asks which of those companies to connect.

### Step 4: Retrieve the access token

Exchange the authorization `code` for an access token as described in [Retrieve an Access Token](https://developer.tryfinch.com/implementation-guide/Connect/Retrieve-Access-Token.md). The first data sync for a new Paylocity connection can take a few minutes to start.

***

## When an employer starts in Finch Connect

Employers can still open Finch Connect from your application or from an emailed link. When they select Paylocity, Finch Connect explains that Paylocity connections start in the Marketplace and lists the steps:

1. Sign in to Paylocity and open the **Marketplace** from the main menu.
2. Find **\<Your application> via Finch** and click **Create Request**.
3. Select the companies to share and submit the request.

Paylocity then sends the administrator through the same flow, and they reach your application with a new session as described in [Step 2](#step-2-handle-the-redirect-from-finch). The original Finch Connect window can be closed.

***

See [Field Support](https://developer.tryfinch.com/integrations/field-support.md) for the fields Finch returns for Paylocity. If you have any questions, reach out to your Finch Developer Success Engineer or [implementation-team@tryfinch.com](mailto:implementation-team@tryfinch.com).