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

# Darwinbox

> Connect Darwinbox to Omni for HR search and workflow actions

The Darwinbox connector indexes HR directory and organization data from Darwinbox and exposes HR workflow actions for the AI assistant and background agents.

## Overview

### What Gets Indexed

| Module               | Content                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------ |
| Employee directory   | Employee profiles, IDs, departments, designations, managers, locations, and employee types |
| Deleted employees    | Deactivated/deleted employee records for lifecycle visibility                              |
| Organization masters | Organization master data used to enrich employee records                                   |
| Positions (optional) | Position master data                                                                       |
| Holidays             | Holiday calendars                                                                          |
| ATS jobs (optional)  | Job/requisition metadata from Darwinbox ATS                                                |

### How It Works

1. You provide your Darwinbox base URL, tenant credentials, and dataset key
2. The connector syncs enabled modules and stores a checkpoint for resumable syncs
3. Synced employee and org data becomes searchable in Omni
4. Optional action modules expose self-service, manager, HR operations, ATS, and report actions to agents

<Note>
  Darwinbox tenant capabilities and API availability vary by deployment. Enable only the sync and action modules your tenant supports.
</Note>

## Prerequisites

Before setting up the Darwinbox connector, ensure you have:

* **Darwinbox API access** for your tenant
* **Base URL** for your Darwinbox instance, such as `https://acme.darwinbox.in`
* **Dataset key** for the APIs Omni should call
* One supported credential set:
  * Basic auth username, password, and API key
  * OAuth2 client credentials
  * Legacy dynamic-token credentials with an authorization code or refresh token
* Omni deployment with the Darwinbox connector service running (profile: `darwinbox`)

## Setup

### Step 1: Connect in Omni

1. Navigate to **Settings** → **Integrations**
2. Find **Darwinbox** and click **Connect**
3. Enter your **Darwinbox base URL**
4. Choose an authentication mode:
   * **Basic auth + API key**: API username, password, API key, and dataset key
   * **OAuth2 client credentials**: Client ID, client secret, optional API key, and dataset key
   * **Legacy dynamic token**: Client ID, client secret, grant type, authorization code or refresh token, optional API key, and dataset key
5. Set the **Default timezone** if needed
6. Choose optional modules:
   * **Sync position master**
   * **Enable ATS jobs/actions**
   * **Enable HR lifecycle actions**
   * **Enable report actions**
7. Click **Connect**
8. Click **Sync** to start the initial sync

<Check>
  Your Darwinbox connector is now configured. Initial indexing time depends on the number of employees and enabled modules.
</Check>

## Managing the Integration

### Viewing Sync Status

Navigate to **Settings** → **Integrations** to view sync status, indexed counts, and errors. Click **Settings** on the source for sync history and source configuration.

### Sync Modes

| Mode            | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------- |
| **Full**        | Syncs enabled employee, organization, holiday, position, and ATS modules from scratch |
| **Incremental** | Uses the connector checkpoint to resume and fetch changed data where supported        |

### Search Operators

The connector registers source-specific operators that work in Search and Chat once the source is running:

| Operator         | Meaning                         |
| ---------------- | ------------------------------- |
| `employee:`      | Filter by Darwinbox employee ID |
| `department:`    | Filter by department            |
| `designation:`   | Filter by designation           |
| `location:`      | Filter by location              |
| `manager:`       | Filter by manager employee ID   |
| `employee_type:` | Filter by employee type         |

### AI Assistant Actions

Darwinbox actions are grouped by module:

| Module                | Example actions                                                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Employee self-service | Get my profile, leave balance, holiday calendar, leave requests, attendance, and timesheet; apply or revoke leave; regularize attendance |
| Manager workflows     | List pending leave approvals, approve/reject leave, view team leave calendars and attendance exceptions, read direct-report profiles     |
| HR operations         | Add/activate/update/deactivate/reactivate employees, update employment details, upload employee documents, fetch employee history        |
| Reports               | Fetch report IDs and run a Darwinbox report by ID                                                                                        |
| ATS                   | List jobs, read job details, fetch candidates, tag/reject candidates, create/archive requisitions                                        |

Write-capable actions are only registered when the corresponding action module is enabled and are subject to the same agent/chat approval and action-allowlist controls as other connector actions.

## Removing the Integration

1. Navigate to **Settings** → **Integrations**
2. Click **Settings** against the Darwinbox source
3. Click **Delete Permanently**
4. Revoke or rotate the Darwinbox API credentials if needed

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection failed">
    Verify the base URL, authentication mode, credentials, API key, and dataset key. Remove any trailing slash from the base URL.
  </Accordion>

  <Accordion title="Some modules fail during sync">
    Confirm your Darwinbox tenant has the relevant API enabled. Disable optional modules such as positions or ATS if your tenant does not expose those endpoints.
  </Accordion>

  <Accordion title="Actions are unavailable">
    Check that the source is enabled, the action module is enabled, and the current chat or background agent is allowed to use the Darwinbox source/action.
  </Accordion>

  <Accordion title="Employee permissions look wrong">
    The connector can use Darwinbox permission data and optional admin/recruiter email lists in source configuration. Review the source settings and verify the synced employee directory contains the expected email addresses.
  </Accordion>
</AccordionGroup>

## Security Considerations

* **Credential storage**: Darwinbox credentials are encrypted at rest in Omni
* **Module scoping**: Keep optional HR, ATS, and report actions disabled unless your team needs them
* **Write actions**: HR lifecycle, leave approval, ATS, and document-upload actions can change data in Darwinbox; expose them only to trusted agents or users
* **Token rotation**: Rotate API keys, passwords, client secrets, and refresh tokens according to your Darwinbox security policy

## What's Next

<CardGroup cols={3}>
  <Card title="Search Your Data" icon="magnifying-glass" href="/user-guide/search">
    Learn how to search HR and organization data
  </Card>

  <Card title="Background Agents" icon="robot" href="/admin/background-agents">
    Use approved HR workflow actions in agents
  </Card>

  <Card title="Connector Management" icon="gear" href="/admin/connector-management">
    Monitor syncs and manage the source
  </Card>
</CardGroup>