# Create Dependents

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

`POST /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_ignore_remote_data`** _(boolean)_
  Excludes the `remote_data` attribute from the response.
- **`truto_enforce_write_schema`** _(boolean)_
  Validates the request body against this method's `request_body_schema` before the request is sent to the underlying integration. When a field marked `required` is missing, Truto responds `400` with the missing field names under `truto_error_insight.missing_required_body_fields` instead of forwarding the call. Only the fields documented in `request_body_schema` are checked. A body carrying a non-empty `remote_data` object is forwarded unchecked, because `remote_data` is merged into the provider request and may already carry the required values. A field the mapping always supplies through its default body is treated as present, and a field that is only conditionally required is reported under `truto_error_insight.conditionally_required_body_fields` rather than rejected. Some integrations declare fields `required` on `update` that the provider only requires on `create`; check `meta/{method}` for the resource before enabling this on update calls. If you sent an `Idempotency-Key` and the request was rejected, use a fresh key when you retry with a corrected body: the idempotency cache is keyed on the integrated account, path and key only — it ignores the query string and the body — so reusing the key replays the rejection. Defaults to `false`, which forwards the request as-is.
- **`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.

## Request body

- **`employee`** _(object)_
  The employee (employees.id) 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
- **`relationship`** _(string)_
  BambooHR accepts spouse, domestic_partner, child, stepchild and foster_child. Other values are not sent.
  Allowed: `spouse`, `domestic_partner`, `child`, `stepchild`, `foster_child`, `ward`, `parent`, `other`, `spouse`, `domestic_partner`, `child`, `stepchild` (+1 more)
- **`gender`** _(string)_
  BambooHR accepts male or female. Other values are not sent.
  Allowed: `male`, `female`, `non_binary`, `other`, `prefer_not_to_disclose`, `male`, `female`
- **`date_of_birth`** _(string)_
  YYYY-MM-DD
- **`ssn`** _(string)_
  The dependent's SSN in plain text; BambooHR stores it encrypted and returns it masked.
- **`is_student`** _(boolean)_
  Whether the dependent is a full-time student
- **`home_location`** _(array<object>)_
  The dependent's home addresses. BambooHR stores one address, so only the first entry is sent. state must be a 2-letter code and country an ISO 3166-1 alpha-2 code.
  - **`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 first phone number is stored as the dependent's home phone.
  - **`number`** _(string)_
    The phone number
  - **`extension`** _(string)_
    The extension of the phone number
  - **`type`** _(string)_
    The type of phone number
- **`remote_data`** _(object)_
  Any additional data that should be passed as part of the request body. This data is not transformed by Truto and is passed as is to the remote API.

## Response body

- **`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.

## Code examples

### Truto CLI

```bash
truto unified hris dependents \
  -m create \
  -a '<integrated_account_id>' \
  -b '{
  "employee": {},
  "first_name": "your_first_name",
  "middle_name": "your_middle_name",
  "last_name": "your_last_name",
  "relationship": "spouse",
  "gender": "male",
  "date_of_birth": "your_date_of_birth",
  "ssn": "your_ssn",
  "is_student": true,
  "home_location": [],
  "phones": [],
  "remote_data": {}
}' \
  -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.create(
  'hris',
  'dependents',
  {
  "employee": {},
  "first_name": "your_first_name",
  "middle_name": "your_middle_name",
  "last_name": "your_last_name",
  "relationship": "spouse",
  "gender": "male",
  "date_of_birth": "your_date_of_birth",
  "ssn": "your_ssn",
  "is_student": true,
  "home_location": [],
  "phones": [],
  "remote_data": {}
},
  { 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():
    result = await truto_api.unified_api.create(
        "hris",
        "dependents",
        {
        "employee": {},
        "first_name": "your_first_name",
        "middle_name": "your_middle_name",
        "last_name": "your_last_name",
        "relationship": "spouse",
        "gender": "male",
        "date_of_birth": "your_date_of_birth",
        "ssn": "your_ssn",
        "is_student": True,
        "home_location": [],
        "phones": [],
        "remote_data": {}
},
        {"integrated_account_id": "<integrated_account_id>"}
    )
    print(result)

asyncio.run(main())
```

### curl

```bash
curl -X POST 'https://api.truto.one/unified/hris/dependents?integrated_account_id=<integrated_account_id>' \
  -H 'Authorization: Bearer <your_api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "employee": {},
  "first_name": "your_first_name",
  "middle_name": "your_middle_name",
  "last_name": "your_last_name",
  "relationship": "spouse",
  "gender": "male",
  "date_of_birth": "your_date_of_birth",
  "ssn": "your_ssn",
  "is_student": true,
  "home_location": [],
  "phones": [],
  "remote_data": {}
}'
```

### JavaScript

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

const body = {
  "employee": {},
  "first_name": "your_first_name",
  "middle_name": "your_middle_name",
  "last_name": "your_last_name",
  "relationship": "spouse",
  "gender": "male",
  "date_of_birth": "your_date_of_birth",
  "ssn": "your_ssn",
  "is_student": true,
  "home_location": [],
  "phones": [],
  "remote_data": {}
};

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

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>"
}
payload = {
    "employee": {},
    "first_name": "your_first_name",
    "middle_name": "your_middle_name",
    "last_name": "your_last_name",
    "relationship": "spouse",
    "gender": "male",
    "date_of_birth": "your_date_of_birth",
    "ssn": "your_ssn",
    "is_student": True,
    "home_location": [],
    "phones": [],
    "remote_data": {}
}

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