# List Dependents

> Source: https://truto.one/docs/api-reference/unified-hris-api/dependents/list/

`GET /unified/hris/dependents`

Resource: **Dependents** · API: **Unified HRIS API**

## Supported integrations

BambooHR

## Query parameters

- **`integrated_account_id`** _(string, required)_
  The ID of the integrated account to use for the request.
- **`truto_response_format`** _(string)_
  The format of the response. - `unified` returns the response with unified mappings applied. - `raw` returns the unprocessed, raw response from the remote API. - `normalized` applies the unified mappings and returns the data in a normalized format. - `stream` returns the response as a stream, which is ideal for transmitting large datasets, files, or binary data. Using streaming mode helps to efficiently handle large payloads or real-time data flows without requiring the entire data to be buffered in memory. - `debug` returns the final unified result alongside raw remote fetch information. The response is an envelope containing `result` (identical to unified mode output) and `debug` (with `requestUrl`, `requestOptions`, `data`, `responseHeaders`, and for list operations: `nextCursor`, `isLooping`, `isEmptyResult`, `resultCount`). When the upstream body exceeds 1 MiB, `data` is replaced by `{ truto_truncated: true, truto_max_bytes, truto_excerpt }`. `debug` is `null` for static responses or when `truto_skip_api_call=true`. Defaults to `unified`.
  Allowed: `unified`, `raw`, `normalized`, `stream`, `debug`
- **`truto_key_by`** _(string)_
  By default the `result` attribute is an array of objects. This parameter allows you to specify a field in each `result` objects to use as key, which transforms the `result` array into an object with the array items keyed by the field. This is useful for when you want to use the result as a lookup table.
- **`truto_ignore_limit`** _(boolean)_
  Ignores the `limit` query parameter.
- **`truto_ignore_remote_data`** _(boolean)_
  Excludes the `remote_data` attribute from the response.
- **`truto_exclude_fields`** _(array<string>)_
  Array of fields to exclude from the response.
- **`remote_query`** _(object)_
  Query parameters to pass to the underlying API without any transformations. Refer [this guide](https://truto.one/docs/api-reference/overview/querying#remote-query-parameters) to see how to structure the query parameters.
- **`employee`** _(object)_
  Only return dependents of this employee (employees.id). When omitted, dependents of all employees are returned.
- **`employee_id`** _(string)_
  Flat alternative to employee.id.

## Response body

- **`result`** _(array<object>)_
  List of Dependents
  - **`id`** _(string, required)_
    The unique identifier for the dependent
  - **`employee`** _(object)_
    The employee the dependent belongs to
    - **`id`** _(string)_
      The unique identifier for employees
    - **`name`** _(string)_
      The name of the employee
  - **`first_name`** _(string)_
    The first name of the dependent
  - **`middle_name`** _(string)_
    The middle name of the dependent
  - **`last_name`** _(string)_
    The last name of the dependent
  - **`name`** _(string)_
    The full name of the dependent
  - **`relationship`** _(string)_
    The dependent's relationship to the employee. Relationships that fit none of the other values, such as grandchild or legal guardian, are returned as other, and the provider's own label stays in remote_data. Registered or civil partnerships that the provider records separately from marriage are returned as domestic_partner.
    Allowed: `spouse`, `domestic_partner`, `child`, `stepchild`, `foster_child`, `ward`, `parent`, `other`
  - **`date_of_birth`** _(string)_
    The date of birth of the dependent, in YYYY-MM-DD format. Empty when the provider masks it.
  - **`gender`** _(string)_
    The gender of the dependent. Empty when the provider value fits none of these.
    Allowed: `male`, `female`, `non_binary`, `other`, `prefer_not_to_disclose`
  - **`ssn`** _(string)_
    The social security number or national identifier of the dependent. Most providers return it masked.
  - **`is_student`** _(boolean)_
    Whether the dependent is a full-time student
  - **`is_disabled`** _(boolean)_
    Whether the dependent has a disability
  - **`is_tobacco_user`** _(boolean)_
    Whether the dependent uses tobacco
  - **`home_location`** _(array<object>)_
    The home addresses of the dependent. Most providers record a single address.
    - **`id`** _(string)_
      The unique identifier for locations
    - **`name`** _(string)_
      This represents the name of the location
    - **`street_1`** _(string)_
      The first line of home address
    - **`street_2`** _(string)_
      The second line of home address
    - **`city`** _(string)_
      The city of the home address
    - **`state`** _(string)_
      The state/province of the home address
    - **`postal_code`** _(string)_
      The postal code of the home address
    - **`country`** _(string)_
      The country of the home address
  - **`phones`** _(array<object>)_
    The phone numbers of the dependent
    - **`number`** _(string)_
      The phone number
    - **`extension`** _(string)_
      The extension of the phone number
    - **`type`** _(string)_
      The type of phone number
  - **`emails`** _(array<object>)_
    The email addresses of the dependent
    - **`email`** _(string)_
      The email address
    - **`type`** _(string)_
      The type of email address
    - **`is_primary`** _(boolean)_
      Whether the email address is primary
  - **`status`** _(string)_
    Whether the person is currently a dependent of the employee. inactive means they no longer are, for example after being removed from coverage. Empty when the provider does not say.
    Allowed: `active`, `inactive`
  - **`start_date`** _(string)_
    When the person became a dependent of the employee, such as the relationship or coverage eligibility start date
  - **`end_date`** _(string)_
    When the person stopped being a dependent of the employee. Empty while they still are
  - **`created_at`** _(string)_
    The date and time the dependent was created
  - **`updated_at`** _(string)_
    The date and time the dependent was last updated
  - **`remote_data`** _(object)_
    Raw data returned from the remote API call.
- **`next_cursor`** _(string)_
  The cursor to use for the next page of results. Pass this value as `next_cursor` in the query parameter in the next request to get the next page of results.
- **`debug`** _(object)_
  Present only when `truto_response_format=debug`. Contains raw fetch details: `requestUrl`, `requestOptions`, `data`, `responseHeaders`, `nextCursor`, `isLooping`, `isEmptyResult`, `resultCount`. `data` is the parsed upstream body; when its JSON form exceeds 1 MiB it is replaced by `{ truto_truncated: true, truto_max_bytes, truto_excerpt }`, where `truto_excerpt` is the leading bytes of that body. The same applies to a string `requestOptions.body`. `null` for static responses or when `truto_skip_api_call=true`.
  - **`requestUrl`** _(string)_
  - **`requestOptions`** _(object)_
  - **`data`** _(unknown)_
  - **`responseHeaders`** _(object)_
  - **`nextCursor`** _(string)_
  - **`isLooping`** _(boolean)_
  - **`isEmptyResult`** _(boolean)_
  - **`resultCount`** _(number)_

## Code examples

### Truto CLI

```bash
truto unified hris dependents \
  -a '<integrated_account_id>' \
  -o json
```

### Truto TS SDK

```typescript
import Truto from '@truto/truto-ts-sdk';

const truto = new Truto({
  token: '<your_api_token>',
});

const result = await truto.unifiedApi.list(
  'hris',
  'dependents',
  { integrated_account_id: '<integrated_account_id>' }
);

console.log(result);
```

### Truto Python SDK

```python
import asyncio
from truto_python_sdk import TrutoApi

truto_api = TrutoApi(token="<your_api_token>")

async def main():
    async for item in truto_api.unified_api.list(
        "hris",
        "dependents",
        {"integrated_account_id": "<integrated_account_id>"}
    ):
        print(item)

asyncio.run(main())
```

### curl

```bash
curl -X GET 'https://api.truto.one/unified/hris/dependents?integrated_account_id=<integrated_account_id>' \
  -H 'Authorization: Bearer <your_api_token>' \
  -H 'Content-Type: application/json'
```

### JavaScript

```javascript
const integratedAccountId = '<integrated_account_id>';

const response = await fetch(`https://api.truto.one/unified/hris/dependents?integrated_account_id=${integratedAccountId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_api_token>',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);
```

### Python

```python
import requests

url = "https://api.truto.one/unified/hris/dependents"
headers = {
    "Authorization": "Bearer <your_api_token>",
    "Content-Type": "application/json",
}
params = {
    "integrated_account_id": "<integrated_account_id>"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```