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

# List Workforce Employees With Contracts

> Retrieve every employee with their contracts and remuneration periods nested in one response

[← Own Workforce API](/api-reference/own-workforce/overview)

Return every employee of the organization tree with their contracts nested inside, and each contract's remuneration **periods** nested inside that. One call instead of walking employee → contracts → remunerations.

<Warning>
  **This endpoint does not paginate and takes no filters.** It walks the header organization and its descendants and returns every employee, every contract and every remuneration period in a single response. For an organization with thousands of employees that payload is large and the request is slow. Use [List Workforce Employees](/api-reference/own-workforce/list) when you can page, and this one only when you genuinely need the whole nested tree.
</Warning>

<Note>
  **Remuneration amounts are not included here.** The nested remuneration objects carry only `start_date` and `end_date`, so this endpoint tells you *when* someone was paid on a given band, not how much. For amounts and currency, call [List Workforce Remunerations](/api-reference/own-workforce/list-remunerations) per contract, or read the aggregates from [Query datasets](/api-reference/datasets/query).
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

## Response

<ResponseField name="items" type="array[object]">
  <Expandable title="employee">
    <ResponseField name="external_employee_id" type="string">
      The identifier from your HR system
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Owning organization — always present here, so you can tell subsidiaries apart
    </ResponseField>

    <ResponseField name="gender" type="string">
      `M`, `F`, `O` or `NS`
    </ResponseField>

    <ResponseField name="disabled_employee" type="string">
      `no_disability`, `with_disability`, `disability_33` or `disability_65`
    </ResponseField>

    <ResponseField name="birth_date" type="string">
      `YYYY-MM-DD`
    </ResponseField>

    <ResponseField name="contracts" type="array[object]">
      <Expandable title="contract">
        <ResponseField name="start_date" type="string">
          `YYYY-MM-DD`
        </ResponseField>

        <ResponseField name="end_date" type="string | null">
          Null means open-ended
        </ResponseField>

        <ResponseField name="remunerations" type="array[object]">
          <Expandable title="remuneration period">
            <ResponseField name="start_date" type="string">
              `YYYY-MM-DD`
            </ResponseField>

            <ResponseField name="end_date" type="string | null">
              Null means still current
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

Note that the employee objects here carry no `id`: they are keyed by `external_employee_id` within their organization. To address an employee on the other endpoints, resolve the UUID through [List Workforce Employees](/api-reference/own-workforce/list).

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/own_workforces/with-contracts-and-remunerations" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os

  import requests

  headers = {
      "x-api-key": os.getenv("DCYCLE_API_KEY"),
      "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
  }

  response = requests.get(
      "https://api.dcycle.io/v1/own_workforces/with-contracts-and-remunerations",
      headers=headers,
      timeout=120,
  )

  for employee in response.json()["items"]:
      spans = sum(len(contract["remunerations"]) for contract in employee["contracts"])
      print(f"{employee['external_employee_id']}: {len(employee['contracts'])} contracts, {spans} pay periods")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const headers = {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID
  };

  axios.get('https://api.dcycle.io/v1/own_workforces/with-contracts-and-remunerations', {
    headers,
    timeout: 120000
  })
  .then(response => {
    response.data.items.forEach(employee => {
      const spans = employee.contracts.reduce((n, c) => n + c.remunerations.length, 0);
      console.log(`${employee.external_employee_id}: ${employee.contracts.length} contracts, ${spans} pay periods`);
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "external_employee_id": "EMP-2024-001",
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "gender": "F",
      "disabled_employee": "no_disability",
      "birth_date": "1990-01-01",
      "contracts": [
        {
          "start_date": "2023-06-01",
          "end_date": null,
          "remunerations": [
            { "start_date": "2023-06-01", "end_date": "2024-12-31" },
            { "start_date": "2025-01-01", "end_date": null }
          ]
        }
      ]
    }
  ]
}
```

## Common Errors

### 401 Unauthorized

**Cause:** the key is invalid, or it does not belong to the organization in `x-organization-id` — the two are looked up as a pair. A request carrying no credentials at all answers `AUTH_REQUIRED` instead.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Invalid API key for organization",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

**Cause:** the key's owner is not an enabled member of the organization in `x-organization-id`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Logged User is not Member of Organization",
  "code": "LOGGED_USER_NOT_MEMBER"
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List employees" icon="users" href="/api-reference/own-workforce/list">
    The paginated, filterable alternative
  </Card>

  <Card title="List remunerations" icon="money-bill" href="/api-reference/own-workforce/list-remunerations">
    Amounts and currency, per contract
  </Card>
</CardGroup>