---
title: Darwinbox
slug: guide/darwinbox
docTags: 
createdAt: 2026-08-07T15:49:08.651Z
---

This guide walks you through connecting your Darwinbox instance to Bindbee.

Darwinbox APIs are restricted to privileged users and are granted on a request basis, so reach out to your Darwinbox account manager for your credentials.

### Before you begin

You will need an active Darwinbox account, and a named contact at Darwinbox (your account manager or customer success representative) who can raise the request internally.

The values that must be provided via the magic link to successfully set up the connection\:v

| **Value**                                  | **Where it comes from** |
| ------------------------------------------ | ----------------------- |
| Tenant (subdomain)                         | Your Darwinbox URL      |
| Region                                     | Your Darwinbox URL      |
| Username                                   | Your Darwinbox rep      |
| Password                                   | Your Darwinbox rep      |
| API Key + Dataset Key (Active Employees)   | Your Darwinbox rep      |
| API Key + Dataset Key (Inactive Employees) | Your Darwinbox rep      |

### Finding your tenant and region

**Step 1:** Sign in to Darwinbox and look at the address bar. Your URL follows the pattern `https://<subdomain>.<domain>/`.

**Step 2:** The **tenant (subdomain)** is the text after `https://` and before the first dot. For example, in `https://acmecorp.darwinbox.in/`, the tenant is `acmecorp`.

**Step 3:** The **region** is the domain your instance is hosted on, which is the part after the first dot, for example `darwinbox.in` or `darwinbox.com`. Select the option in Bindbee that matches your URL exactly.

### Requesting your credentials from Darwinbox

**Step 4:** Raise a request with your Darwinbox account manager saying you are enabling an API integration with a third-party platform, and ask them to provide:

- A **username** and **password** for an integration user
- An **API Key** and **Dataset Key** for **all active employees**
- An **API Key** and **Dataset Key** for **all inactive employees**

Ask for the integration user to be a dedicated service account rather than a named employee's login. A personal login will break the connection the moment that person leaves or has their access changed.

The active and inactive employee datasets are issued as separate key pairs. If you only receive one pair, please confirm which dataset it covers.

**Step 5:** In the same request, make sure that all the required scopes are enabled.

**Step 6:** Store the credentials somewhere secure when they arrive.

### Entering the credentials in Bindbee

**Step 7:** In the Bindbee authorization flow, enter your **tenant (subdomain)**, **region**, **username**, and **password**, then continue.

**Step 8:** Enter the **API Key** and **Dataset Key** for **active employees**.

**Step 9:** Enter the **API Key** and **Dataset Key** for **inactive employees**, then submit.

Bindbee validates the credentials immediately and begins the first sync once they pass.

### Troubleshooting

| **Symptom**                                 | **Likely cause**                                                                                                                         |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication error on submit              | Wrong username or password, or the API keys were not issued against that integration user                                                |
| Connection succeeds but no employees return | The keys were issued against the wrong module or endpoint. They need to cover the **Core** module and the `/masterapi/employee` endpoint |
| Employees sync but fields are blank         | The required fields are not enabled for your `masterapi`. Please contact your representative to enable the necessary scopes              |