> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://docs.deel.wtf/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.deel.wtf/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server.

# Get employees from organization integrated with external benefits vendor

GET https://api.letsdeel.com/rest/benefits/legal-entities/{legal_entity_id}/employees

Returns employees belonging to the legal entity that has been integrated with an external benefits vendor. Results can be filtered to include only employees with active contracts.

 **Token scopes**: `people:read`

Reference: https://docs.deel.wtf/api/reference/endpoints/employees/get-employees-from-organization-integrated-with-external-benefits-vendor-v-2026-01-01

## Authentication

- `Authorization` header (bearer token, required) — ## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.deel.training/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication)
- `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

## Servers

- `https://api.letsdeel.com/rest` (Production, default)
- `https://api-staging.letsdeel.com/rest` (Demo)

## Request

### Path parameters

- `legal_entity_id` (string, required) — Id from the legal entity to fetch data

### Query parameters

- `active_contracts` (boolean, optional, default: true) — Fetch only active contracts for employees
- `items_per_page` (integer, optional, default: 100) — Items per page
- `offset` (integer, optional, default: 0) — Items to be skipped when searching

## Response

### 200

Successful operation.

- `data` (BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaData, optional)
- `page` (BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaPage, optional)

## Errors

### 400 Bad Request Error

Bad Request - Invalid input parameters or validation error.

- `error` (string, required) — Error message describing what went wrong with the request.

### 401 Unauthorized Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 403 Forbidden Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 404 Not Found Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 500 Internal Server Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

## Types

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaData

- `data` (list of BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItems, optional) — List of employees

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaPage

- `offset` (integer, optional) — Items to be skipped when searching
- `total_rows` (integer, optional) — Total number of rows
- `items_per_page` (integer, optional) — Items per page

### ApiErrorRequest

- `method` (string, optional) — The HTTP method of the failed request
- `url` (string, optional) — The relative URL of the failed request
- `status` (double, optional) — The status code of the response
- `api_req_id` (string, optional) — The request ID of the failed request
- `docs` (string, optional) — A link to the official documentation for the requested endpoint resource
- `source` (string, optional) — The source handler which produced the returned error
- `code` (double, optional) — The code of the source handler which produced the returned error

### ApiError

- `message` (string, optional) — A description of the returned error
- `path` (string, optional) — The JSON path where input validation failed

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItems

- `id` (string, optional) — Unique identifier for the employee.
- `phones` (list of BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsPhonesItems, optional) — List of phone numbers associated with the employee.
- `status` (enum, optional) — The employee status given his contracts.
  - Allowed values: `draft`, `pending_invite`, `invited`, `onboarding`, `onboarding_at_risk`, `onboarding_overdue`, `onboarded`, `offboarding`, `active`, `inactive`, `quote_requires_changes`, `in_review`, `no_active_contracts`
- `addresses` (list of BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsAddressesItems, optional) — List of addresses associated with the employee.
- `contracts` (list of BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsContractsItems, optional) — List of contracts associated with the employee.
- `hire_date` (string, optional, nullable) — Employee date of first contract.
- `work_email` (string, optional, nullable) — Employee work email address.
- `date_of_birth` (string, optional, nullable) — Employee date of birth.
- `marital_status` (enum, optional, nullable) — The marital status of the employee.
  - Allowed values: `Common Law`, `Divorced`, `Married`, `Registered Partnership`, `Separated`, `Single`, `Widowed`
- `personal_email` (string, optional) — Employee personal email address.
- `document_number` (BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsDocumentNumber, optional) — Document number of employee identification document.
- `legal_last_name` (string, optional) — Employee legal last name.
- `legal_first_name` (string, optional) — Employee legal first name.
- `legal_middle_name` (string, optional, nullable) — Employee legal middle name.
- `takes_owners_draw` (boolean, optional) — Indicates if the employee takes an owner draw.
- `ownership_percentage` (double, optional) — The percentage of business ownership by the employee.

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsPhonesItems

- `type` (enum, optional) — The type of phone number.
  - Allowed values: `PERSONAL`, `WORK`, `HOME`
- `dial_code` (string, optional) — The international dial code.
- `phone_number` (string, optional) — The phone number.

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsAddressesItems

- `zip` (string, optional, nullable) — The ZIP or postal code part of the address.
- `city` (string, optional, nullable) — The city part of the address.
- `type` (string, optional) — The type of address, e.g., HOME, POSTAL.
- `state` (string, optional, nullable) — The state part of the address.
- `street` (string, optional, nullable) — The street part of the address.
- `country` (string, optional) — The country part of the address.

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsContractsItems

- `id` (string, optional) — Unique identifier for the contract.
- `flsa` (BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsContractsItemsFlsa, optional) — Indicates if the contract is compliant with the Fair Labor Standards Act.
- `status` (string, optional) — The contract status.
- `end_date` (string, optional, nullable) — The end date of the contract, if applicable.
- `job_title` (string, optional, nullable) — Job title or name of the contract.
- `start_date` (string, optional) — The start date of the contract.
- `compensations` (list of BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsContractsItemsCompensationsItems, optional) — List of compensations associated with the contract.
- `contract_type` (enum, optional) — The type of contract.
  - Allowed values: `direct_employee`, `contractor`, `eor`, `peo`, `hris_direct_employee`, `contractor_outside_deel`, `hris_direct_contractor`, `person_without_contract`
- `contract_status` (enum, optional) — The contract status.
  - Allowed values: `new`, `onboarding`, `onboarded`, `under_review`, `waiting_for_employee_contract`, `waiting_for_approval`, `waiting_for_client_sign`, `waiting_for_legal_review`, `waiting_for_provider_sign`, `processing_payment`, `waiting_for_contractor_sign`, `waiting_for_eor_sign`, `waiting_for_employee_sign`, `awaiting_deposit_payment`, `in_progress`, `completed`, `cancelled`, `user_cancelled`, `rejected`, `waiting_for_client_payment`, `waiting_for_hris_employee_sign`
- `employment_type` (enum, optional) — The employment type.
  - Allowed values: `full_time`, `part_time`, `on_leave`, `terminated`
- `estimated_week_working_hours` (double, optional) — Estimated number of working hours per week.

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsDocumentNumber

Document number of employee identification document.

- string
- BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsDocumentNumber1

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsContractsItemsFlsa

Indicates if the contract is compliant with the Fair Labor Standards Act.

- boolean
- enum
  - Allowed values: `Exempt`

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsContractsItemsCompensationsItems

Details about the compensations.

- `rate` (double, optional) — The rate of compensation.
- `type` (enum, optional) — The type of compensation, either MAIN or VARIABLE.
  - Allowed values: `MAIN`, `VARIABLE`
- `scale` (enum, optional, nullable) — The scale of the compensation.
  - Allowed values: `hourly`, `annual`, `biweekly`, `weekly`, `monthly`, `semimonthly`
- `currency` (string, optional) — The currency of the compensation.
- `cycle_scale` (string, optional, nullable) — The cycle scale of the compensation.
- `variable_compensation_type` (enum, optional, nullable) — The type of variable compensation, either FIXED or PERCENTAGE.
  - Allowed values: `FIXED`, `PERCENTAGE`

### BenefitsLegalEntitiesLegalEntityIdEmployeesGetResponsesContentApplicationJsonSchemaDataDataItemsDocumentNumber1

- `skip_reason` (string, required) — Reason for skipping.

## Examples

**Response**

```json
{
  "data": {
    "data": [
      {
        "id": "810d4392-1857-4bd0-98a8-d18ebedbc882",
        "phones": [
          {
            "type": "PERSONAL",
            "dial_code": "+1",
            "phone_number": "1234567890"
          }
        ],
        "status": "active",
        "addresses": [
          {
            "zip": "12345",
            "city": "New York",
            "type": "HOME",
            "state": "NY",
            "street": "123 Main St",
            "country": "US"
          }
        ],
        "contracts": [
          {
            "id": "k628xgg",
            "flsa": "Exempt",
            "status": "active",
            "end_date": "2022-12-31",
            "job_title": "Software Engineer",
            "start_date": "2022-01-01",
            "compensations": [
              {
                "rate": 1000,
                "type": "MAIN",
                "scale": "hourly",
                "currency": "USD",
                "cycle_scale": "hour",
                "variable_compensation_type": "FIXED"
              }
            ],
            "contract_type": "direct_employee",
            "contract_status": "waiting_for_provider_sign",
            "employment_type": "full_time",
            "estimated_week_working_hours": 40
          }
        ],
        "hire_date": "2022-01-01",
        "work_email": "test@example.com",
        "date_of_birth": "1990-01-01",
        "marital_status": "Single",
        "personal_email": "test2@example.com",
        "document_number": "123456789",
        "legal_last_name": "Doe",
        "legal_first_name": "John",
        "legal_middle_name": "Doe",
        "takes_owners_draw": true,
        "ownership_percentage": 50
      }
    ]
  },
  "page": {
    "offset": 0,
    "total_rows": 100,
    "items_per_page": 100
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/benefits/legal-entities/123456/employees"

querystring = {"active_contracts":"true","items_per_page":"100","offset":"0"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/benefits/legal-entities/123456/employees?active_contracts=true&items_per_page=100&offset=0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.letsdeel.com/rest/benefits/legal-entities/123456/employees?active_contracts=true&items_per_page=100&offset=0"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.letsdeel.com/rest/benefits/legal-entities/123456/employees?active_contracts=true&items_per_page=100&offset=0")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.letsdeel.com/rest/benefits/legal-entities/123456/employees?active_contracts=true&items_per_page=100&offset=0")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.letsdeel.com/rest/benefits/legal-entities/123456/employees?active_contracts=true&items_per_page=100&offset=0', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/benefits/legal-entities/123456/employees?active_contracts=true&items_per_page=100&offset=0");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/benefits/legal-entities/123456/employees?active_contracts=true&items_per_page=100&offset=0")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```