> ## 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.

# Get Workforce Unique Values

> List the distinct values of a filterable employee field, with a count per value

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

Return the distinct values of one filterable field, each with a human-readable label and the number of employee rows carrying it. This is what populates the file filter on [List Workforce Employees](/api-reference/own-workforce/list) without paging the whole list first.

## 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>

### Query Parameters

<ParamField query="field" type="string" required>
  The field to enumerate.

  **Available values:** `file_id`

  Today `file_id` is the only accepted value; any other is rejected with 422. The parameter exists so the contract can grow without a new endpoint.

  **Example:** `field=file_id`
</ParamField>

## Response

<ResponseField name="field" type="string">
  Echo of the field that was queried
</ResponseField>

<ResponseField name="total_count" type="integer">
  Number of distinct values returned
</ResponseField>

<ResponseField name="values" type="array[object]">
  <Expandable title="value">
    <ResponseField name="value" type="string | null">
      The raw value to send back as a filter — here a file UUID. Null represents rows with no file.
    </ResponseField>

    <ResponseField name="label" type="string | null">
      Human-readable label — here the file name
    </ResponseField>

    <ResponseField name="count" type="integer">
      Number of employee rows with this value
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  To filter the list for the null bucket, pass the nil UUID `00000000-0000-0000-0000-000000000000` as `file_id[]`, not an empty value.
</Note>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/own_workforces/unique-values?field=file_id" \
    -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/unique-values",
      headers=headers,
      params={"field": "file_id"},
  )

  result = response.json()
  for item in result["values"]:
      print(f"{item['label']}: {item['count']} employees")
  ```

  ```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/unique-values', {
    headers,
    params: { field: 'file_id' }
  })
  .then(response => {
    response.data.values.forEach(item => console.log(`${item.label}: ${item.count} employees`));
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "field": "file_id",
  "total_count": 2,
  "values": [
    {
      "value": "9f1c7f2a-64a1-4b2c-9d3e-70a5b8c1d2e3",
      "label": "workforce_2026.csv",
      "count": 145
    },
    {
      "value": null,
      "label": null,
      "count": 3
    }
  ]
}
```

## 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"
}
```

### 422 Unprocessable Entity

**Cause:** `field` missing, or set to something other than `file_id`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "type": "enum",
      "loc": ["query", "field"],
      "msg": "Input should be 'file_id'"
    }
  ]
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List employees" icon="users" href="/api-reference/own-workforce/list">
    Apply the value as `file_id[]`
  </Card>

  <Card title="Trainings unique values" icon="filter" href="/api-reference/own-workforce/unique-values-trainings">
    The same endpoint for trainings
  </Card>
</CardGroup>