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

# Connect your app to Deel

> Connect your app to Deel, the global payroll and HR platform, to build with your contracts, people, timesheets, time off, and payments.

[Deel](https://www.deel.com/) is a global payroll and HR platform for hiring and paying employees and contractors in other countries.

The Deel connector lets your Lovable app read and update your company's Deel data, such as contracts, people, timesheets, and time off. It's designed for internal tools that HR, finance, and operations teams build, such as team directories, timesheet portals, and payroll reports.

Deel is available as an [app + chat connector](https://docs.lovable.dev/integrations/app-connectors.md): one shared connection that works in [Chats](https://docs.lovable.dev/features/chats.md), in the project chat while you build, and in your published apps.

With Deel, your app can:

* List contracts and people, with their departments, teams, and organization structure
* Log hours on contractor timesheets, and approve or reject timesheets and invoice adjustments
* Read time-off requests and balances, and create or review requests
* Read payments and their breakdowns
* React when Deel reports a change, such as a new contract or a submitted timesheet

## Common use cases and example apps

These examples show what you can build with Deel, each with a prompt to start from.

| Example app | Example prompt | Description |
| :- | :- | :- |
| **Team directory** | *Use Deel and build a team directory that shows everyone's role, department, and country.* | **Give the company one place to find colleagues.** The app caches people and departments from Deel, so the directory loads without calling Deel on every visit. |
| **Contractor timesheet portal** | *Use Deel and build a portal where contractors sign in and log their hours each week.* | **Collect hours without giving contractors access to Deel.** The app signs each contractor in and logs hours only on their own Deel contract. |
| **Timesheet approval queue** | *Use Deel and build a page where managers review and approve submitted timesheets.* | **Approve hours before payroll closes.** The app lists pending timesheets and sends each approval or rejection back to Deel. |
| **Time-off tracker** | *Use Deel and build a calendar that shows who is out this month and each person's remaining balance.* | **Plan around absences.** The app reads time-off requests and remaining balances and shows them on a shared calendar. |
| **Payroll cost report** | *Use Deel and build a monthly report of payments by country and currency.* | **See what the company pays and where.** The app reads payments and their breakdowns and groups the totals by month, country, and currency. |
| **New hire onboarding tracker** | *Use Deel and build a checklist that starts when a new contract is created in Deel.* | **Start onboarding the moment someone joins.** The app gets a notification from Deel for each new contract and creates an onboarding checklist. |

## How to connect Deel

Who can create Deel connections depends on your plan and workspace settings. App + chat connectors are available by default. On Business and Enterprise plans, [Who can create connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients) starts at **Admins**. Some Enterprise workspaces start at **No one**, which disables the connector. An admin or owner changes it in **Connectors → Admin settings → App + chat connectors**.

You can create multiple Deel connections using different API tokens, for example one for your [Deel sandbox](#test-with-the-deel-sandbox) and one for production.

When the connection is created, you can [link it to the projects](https://docs.lovable.dev/integrations/app-connectors.md#link-a-connection-to-a-project) where you want to use it. Anyone building in a project can ask Lovable in the project chat to link their project to it. Linking follows the connection's access rules.

### Prerequisites

Before connecting Deel, make sure you have:

* A Deel account with access to **More → Developer**
* A Deel organization API token
* Permission to **create connections** in your Lovable workspace (see [Who can create connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients))

> [!NOTE]
>
> An organization token acts for your whole Deel organization, so every app linked to the connection can reach all the data its scopes allow. For an app that employees or contractors use, ask Lovable to sign people in and show each person only their own records. Without sign-in, anyone who opens your app can read your organization's Deel data, including contracts and payroll.
>
> Billing is handled directly by Deel, not Lovable.

### Step 1: Get a Deel organization API token

A Deel organization API token lets your Lovable app call the Deel API for your company, limited to the scopes you choose.

To create a Deel organization API token:

**1. Open Deel**

Sign in to [Deel](https://app.deel.com/). For a sandbox token, start with [Test with the Deel sandbox](#test-with-the-deel-sandbox).

**2. Open access tokens**

Go to **More → Developer**, or open [Deel's developer settings](https://app.deel.com/settings/developer) directly, and click the **Access Tokens** tab.

**3. Create the token**

Click **Generate new token** and select **Organization token**. A **Personal token** carries only your own Deel access and cannot read your organization's data.

**4. Choose scopes**

Select the scopes for the data your app uses, for example `contracts:read`, `people:read`, `timesheets:write`, and `time-off:read`. Each endpoint page in the [Deel API reference](https://developer.deel.com/api/introduction) lists the scopes it needs.

To let Deel notify your app about changes, also select `webhooks:write`.

Lovable does not check scopes when you connect. When your app calls Deel without a scope it needs, Deel rejects the request and names the missing scope.

**5. Copy the token**

Click **Generate**, then copy the token and store it securely. Deel shows the token only once.

> [!WARNING]
>
> Your API token functions like a password. Keep it secure and never share it publicly. You'll need it in the next step.

See Deel documentation for more: [Deel API authentication](https://developer.deel.com/api/authentication).

### Step 2: Connect Deel to Lovable

Choose the Deel environment and paste your token to create the connection.

**1. Open Deel in Connectors**

Open [Connectors](https://lovable.dev/dashboard?connectors) and select **Deel**. For the other places to open the catalog from, see [Where to find connectors](https://docs.lovable.dev/integrations/introduction#where-to-find-connectors).

**2. Add a connection**

Click **Connect** on the connector page. The form is split into collapsible sections, **Details**, **Configure connection**, and **Sharing**.

**3. Name the connection**

Under **Details**, Lovable fills in a name for the connection, which you can change. The name is only used inside Lovable to identify the connection.

**4. Configure the connection**

Under **Configure connection**, enter:

1. **Environment**: **Production** (the default) for your real Deel organization, or **Sandbox** for your Deel sandbox.
2. **Organization API token**: the token from Step 1, created in the environment you selected.

**5. Choose who can use this connection**

Under **Sharing**, the connection is private to you by default and shows a **Private** label. To share it, click **Share with others**. Then add workspace members by email, or click **Invite entire workspace** to make the connection available to everyone in your Lovable workspace.

See [Who can use connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-use-connections-and-clients) for more information.

**6. Connect**

Click **Connect** at the bottom of the form. Lovable verifies the token against the Deel API before saving the connection.

When connected, anyone building in a project can ask Lovable in the project chat to link their project to Deel. Linking follows the connection's access rules. Your Lovable apps can then read and update contracts, people, timesheets, and time off in Deel.

## Test with the Deel sandbox

Deel's sandbox is a separate Deel environment with sample data and its own API tokens. Writes on a production connection change real contracts, timesheets, and payroll, so build and test write flows on a sandbox connection first.

To use the sandbox:

**1. Create the sandbox**

In Deel, go to **More → Developer**, open the **API Sandbox** tab, and click **Create Sandbox**. Enter an email address and password for the sandbox account and click **Confirm**. If your organization already has a sandbox, skip this step.

**2. Create a sandbox token**

Sign in to the sandbox with that email address and password and create an organization API token, as in [Step 1](#step-1-get-a-deel-organization-api-token). Production and sandbox tokens work only in their own environment.

**3. Create a sandbox connection**

Create a second Deel connection as in [Step 2](#step-2-connect-deel-to-lovable), with **Environment** set to **Sandbox**.

**4. Link the sandbox connection while you build**

Ask Lovable in the project chat to link your project to the sandbox connection. When the app works, link the project to the production connection instead.

Before Lovable builds a write flow on a production connection, it warns you and suggests a sandbox connection. You still create and link that connection yourself.

See Deel documentation for more: [Deel API sandbox](https://developer.deel.com/api/stable/sandbox).

## Get notified when something changes in Deel

Your app can react to changes in Deel, such as a new contract or a submitted timesheet, instead of checking Deel on a schedule. Deel sends a webhook: a message to an address in your app each time the event happens.

The connection does not set this up on its own. Ask Lovable to build it, for example:

```text wrap theme={null}
Use Deel and create an onboarding checklist each time a new contract is created.
```

Lovable then builds:

* A public address in your app that receives Deel's messages
* A subscription in Deel that sends the messages to that address
* A check on every message that confirms it came from Deel, so your app rejects anything else

The subscription needs the `webhooks:write` scope and starts on your app's preview address. After you publish the app, ask Lovable to point the subscription at the published app.

Your app must accept each message within 30 seconds. Deel retries failed messages and disables the subscription after 10 failures.

## Update the token

To replace the token on an existing connection:

**1. Open the connection**

Open [Connectors](https://lovable.dev/dashboard?connectors), select **Deel**, and open the connection you want to update.

**2. Enter the new token**

Under **Configure connection**, paste the new token in **Organization API token**.

**3. Save the token**

Click **Update**. Lovable checks the new token with the Deel API before saving it.

## Limitations

The Deel connector cannot:

* Create Deel credentials from your app, such as API tokens, Deel sign-in links, or worker sessions. You create the organization token in Deel yourself.
* Make more than 5 requests per second. Deel sets this limit for your whole Deel organization, shared with every other tool that uses it, so Lovable builds apps that cache Deel data.
* Support per-end-user Deel login. Each connection represents a single Deel organization token shared across all projects linked to it.

## Troubleshooting

Use these checks when connecting fails or a Deel request returns an unexpected status.

> [accordion] Deel did not validate your credentials.
>
> Deel rejected the token when Lovable checked it. Click **Show error** to see Deel's response. The usual cause is a token from the other environment, such as a sandbox token on a **Production** connection. Set **Environment** to match the token, or create a token in the selected environment.

> [accordion] Deel rejects a request for a missing scope
>
> Create a new token in Deel with the scope Deel names, for example `time-off:read`, then [update the token](#update-the-token) on the connection.

> [accordion] Requests fail after they worked before
>
> The token was revoked or expired in Deel. Create a new token and [update the token](#update-the-token) on the connection.

> [accordion] Deel returns too many requests
>
> Deel sends a `Retry-After` time, and apps that Lovable builds wait that long before retrying. If it keeps happening, ask Lovable to cache more of what your app reads, or check which other tools share the Deel organization.

> [accordion] Your app no longer receives Deel notifications
>
> Deel disabled the subscription after 10 failed messages. Check that your app replies within 30 seconds, then ask Lovable to create the subscription again.

## Manage your Deel connection

Connections are managed from [**Connectors**](https://lovable.dev/dashboard?connectors): select **Deel**, then open the connection.

* **Unlink projects** to remove Deel access from specific projects while keeping the connection available for others. See [Unlink projects from a connection](https://docs.lovable.dev/integrations/app-connectors.md#unlink-projects-from-a-connection) for the steps.
* **Delete the connection** to remove it from the workspace entirely. Deleting is permanent. It removes the credentials from all linked projects, and app features that use Deel stop working until a new connection is added. See [Delete a connection](https://docs.lovable.dev/integrations/app-connectors.md#delete-a-connection) for the steps and who can delete.