> For the complete documentation index, see [llms.txt](https://api-docs.myhappyforce.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.myhappyforce.com/docs/api-reference/characteristics-resource.md).

# Characteristics Resource

## GET /api/v1/company/characteristics/{characteristicId}

>

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"SegmentDateDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"ranges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true},"deletedRanges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true}}}],"description":"Date-based company segment implementation","required":["questionType"]},"SegmentBaseDTO":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/SegmentListDTO","DATE":"#/components/schemas/SegmentDateDTO","TREE":"#/components/schemas/SegmentTreeDTO"}},"properties":{"id":{"type":"string"},"description":{"type":"string"},"question":{"$ref":"#/components/schemas/MultiLanguage"},"privated":{"type":"boolean"},"isCore":{"type":"boolean"},"employeeCount":{"type":"integer","format":"int32"},"core":{"type":"boolean"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}},"required":["description","questionType"]},"MultiLanguage":{"type":"object","description":"A translatable text value: a required default value plus optional per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\"). Consumers resolve the user's language from langValues (falling back to the base language, then to defaultValue).","properties":{"defaultValue":{"type":"string","description":"Fallback text used when there is no entry in langValues for the requested language.","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\")."},"valid":{"type":"boolean"}},"required":["defaultValue"]},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN","TREE"]},"CompanySegmentDateRangeDTO":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"integer","format":"int32"},"fromType":{"$ref":"#/components/schemas/DateGroupingTypes"},"to":{"type":"integer","format":"int32"},"toType":{"$ref":"#/components/schemas/DateGroupingTypes"},"name":{"type":"string"},"employeeCount":{"type":"integer","format":"int32"}}},"DateGroupingTypes":{"type":"string","description":"Types of date grouping intervals","enum":["DAY","WEEK","MONTH","QUARTER","NON_NATURAL_QUARTER","YEAR"]},"SegmentListDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}},"deletedValues":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}}}}],"description":"List-based company segment implementation","required":["questionType"]},"CompanySegmentListItemDTO":{"type":"object","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"employeeCount":{"type":"integer","format":"int32"}}},"SegmentTreeDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"rootNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"deletedNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}}}}],"description":"Tree-based company segment (hierarchical / N levels). Employees are assigned to leaf nodes only; filters may target any level and the server expands parent selections to descendant leaves.","required":["questionType"]},"TreeNodeDTO":{"type":"object","description":"A single node in a tree segment. May be a leaf (children empty) or an internal node (children non-empty).","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"children":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"employeeCount":{"type":"integer","format":"int32","description":"For leaf nodes: count of employees directly assigned. For internal nodes: recursive sum of descendant leaves' counts."}}}}},"paths":{"/api/v1/company/characteristics/{characteristicId}":{"get":{"tags":["characteristics-resource"],"operationId":"getCharacteristic","parameters":[{"name":"characteristicId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SegmentDateDTO"},{"$ref":"#/components/schemas/SegmentListDTO"},{"$ref":"#/components/schemas/SegmentTreeDTO"}]}}}}}}}}}
```

## PUT /api/v1/company/characteristics/{characteristicId}

>

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"SegmentDateDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"ranges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true},"deletedRanges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true}}}],"description":"Date-based company segment implementation","required":["questionType"]},"SegmentBaseDTO":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/SegmentListDTO","DATE":"#/components/schemas/SegmentDateDTO","TREE":"#/components/schemas/SegmentTreeDTO"}},"properties":{"id":{"type":"string"},"description":{"type":"string"},"question":{"$ref":"#/components/schemas/MultiLanguage"},"privated":{"type":"boolean"},"isCore":{"type":"boolean"},"employeeCount":{"type":"integer","format":"int32"},"core":{"type":"boolean"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}},"required":["description","questionType"]},"MultiLanguage":{"type":"object","description":"A translatable text value: a required default value plus optional per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\"). Consumers resolve the user's language from langValues (falling back to the base language, then to defaultValue).","properties":{"defaultValue":{"type":"string","description":"Fallback text used when there is no entry in langValues for the requested language.","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\")."},"valid":{"type":"boolean"}},"required":["defaultValue"]},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN","TREE"]},"CompanySegmentDateRangeDTO":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"integer","format":"int32"},"fromType":{"$ref":"#/components/schemas/DateGroupingTypes"},"to":{"type":"integer","format":"int32"},"toType":{"$ref":"#/components/schemas/DateGroupingTypes"},"name":{"type":"string"},"employeeCount":{"type":"integer","format":"int32"}}},"DateGroupingTypes":{"type":"string","description":"Types of date grouping intervals","enum":["DAY","WEEK","MONTH","QUARTER","NON_NATURAL_QUARTER","YEAR"]},"SegmentListDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}},"deletedValues":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}}}}],"description":"List-based company segment implementation","required":["questionType"]},"CompanySegmentListItemDTO":{"type":"object","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"employeeCount":{"type":"integer","format":"int32"}}},"SegmentTreeDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"rootNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"deletedNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}}}}],"description":"Tree-based company segment (hierarchical / N levels). Employees are assigned to leaf nodes only; filters may target any level and the server expands parent selections to descendant leaves.","required":["questionType"]},"TreeNodeDTO":{"type":"object","description":"A single node in a tree segment. May be a leaf (children empty) or an internal node (children non-empty).","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"children":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"employeeCount":{"type":"integer","format":"int32","description":"For leaf nodes: count of employees directly assigned. For internal nodes: recursive sum of descendant leaves' counts."}}}}},"paths":{"/api/v1/company/characteristics/{characteristicId}":{"put":{"tags":["characteristics-resource"],"operationId":"updateCompanyCharacteristics","parameters":[{"name":"characteristicId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SegmentDateDTO"},{"$ref":"#/components/schemas/SegmentListDTO"},{"$ref":"#/components/schemas/SegmentTreeDTO"}]}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SegmentDateDTO"},{"$ref":"#/components/schemas/SegmentListDTO"},{"$ref":"#/components/schemas/SegmentTreeDTO"}]}}}}}}}}}
```

## DELETE /api/v1/company/characteristics/{characteristicId}

>

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"SegmentDateDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"ranges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true},"deletedRanges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true}}}],"description":"Date-based company segment implementation","required":["questionType"]},"SegmentBaseDTO":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/SegmentListDTO","DATE":"#/components/schemas/SegmentDateDTO","TREE":"#/components/schemas/SegmentTreeDTO"}},"properties":{"id":{"type":"string"},"description":{"type":"string"},"question":{"$ref":"#/components/schemas/MultiLanguage"},"privated":{"type":"boolean"},"isCore":{"type":"boolean"},"employeeCount":{"type":"integer","format":"int32"},"core":{"type":"boolean"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}},"required":["description","questionType"]},"MultiLanguage":{"type":"object","description":"A translatable text value: a required default value plus optional per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\"). Consumers resolve the user's language from langValues (falling back to the base language, then to defaultValue).","properties":{"defaultValue":{"type":"string","description":"Fallback text used when there is no entry in langValues for the requested language.","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\")."},"valid":{"type":"boolean"}},"required":["defaultValue"]},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN","TREE"]},"CompanySegmentDateRangeDTO":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"integer","format":"int32"},"fromType":{"$ref":"#/components/schemas/DateGroupingTypes"},"to":{"type":"integer","format":"int32"},"toType":{"$ref":"#/components/schemas/DateGroupingTypes"},"name":{"type":"string"},"employeeCount":{"type":"integer","format":"int32"}}},"DateGroupingTypes":{"type":"string","description":"Types of date grouping intervals","enum":["DAY","WEEK","MONTH","QUARTER","NON_NATURAL_QUARTER","YEAR"]},"SegmentListDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}},"deletedValues":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}}}}],"description":"List-based company segment implementation","required":["questionType"]},"CompanySegmentListItemDTO":{"type":"object","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"employeeCount":{"type":"integer","format":"int32"}}},"SegmentTreeDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"rootNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"deletedNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}}}}],"description":"Tree-based company segment (hierarchical / N levels). Employees are assigned to leaf nodes only; filters may target any level and the server expands parent selections to descendant leaves.","required":["questionType"]},"TreeNodeDTO":{"type":"object","description":"A single node in a tree segment. May be a leaf (children empty) or an internal node (children non-empty).","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"children":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"employeeCount":{"type":"integer","format":"int32","description":"For leaf nodes: count of employees directly assigned. For internal nodes: recursive sum of descendant leaves' counts."}}}}},"paths":{"/api/v1/company/characteristics/{characteristicId}":{"delete":{"tags":["characteristics-resource"],"operationId":"deleteCompanyCharacteristics","parameters":[{"name":"characteristicId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SegmentDateDTO"},{"$ref":"#/components/schemas/SegmentListDTO"},{"$ref":"#/components/schemas/SegmentTreeDTO"}]}}}}}}}}}
```

## GET /api/v1/company/characteristics

>

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"SegmentDateDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"ranges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true},"deletedRanges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true}}}],"description":"Date-based company segment implementation","required":["questionType"]},"SegmentBaseDTO":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/SegmentListDTO","DATE":"#/components/schemas/SegmentDateDTO","TREE":"#/components/schemas/SegmentTreeDTO"}},"properties":{"id":{"type":"string"},"description":{"type":"string"},"question":{"$ref":"#/components/schemas/MultiLanguage"},"privated":{"type":"boolean"},"isCore":{"type":"boolean"},"employeeCount":{"type":"integer","format":"int32"},"core":{"type":"boolean"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}},"required":["description","questionType"]},"MultiLanguage":{"type":"object","description":"A translatable text value: a required default value plus optional per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\"). Consumers resolve the user's language from langValues (falling back to the base language, then to defaultValue).","properties":{"defaultValue":{"type":"string","description":"Fallback text used when there is no entry in langValues for the requested language.","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\")."},"valid":{"type":"boolean"}},"required":["defaultValue"]},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN","TREE"]},"CompanySegmentDateRangeDTO":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"integer","format":"int32"},"fromType":{"$ref":"#/components/schemas/DateGroupingTypes"},"to":{"type":"integer","format":"int32"},"toType":{"$ref":"#/components/schemas/DateGroupingTypes"},"name":{"type":"string"},"employeeCount":{"type":"integer","format":"int32"}}},"DateGroupingTypes":{"type":"string","description":"Types of date grouping intervals","enum":["DAY","WEEK","MONTH","QUARTER","NON_NATURAL_QUARTER","YEAR"]},"SegmentListDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}},"deletedValues":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}}}}],"description":"List-based company segment implementation","required":["questionType"]},"CompanySegmentListItemDTO":{"type":"object","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"employeeCount":{"type":"integer","format":"int32"}}},"SegmentTreeDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"rootNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"deletedNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}}}}],"description":"Tree-based company segment (hierarchical / N levels). Employees are assigned to leaf nodes only; filters may target any level and the server expands parent selections to descendant leaves.","required":["questionType"]},"TreeNodeDTO":{"type":"object","description":"A single node in a tree segment. May be a leaf (children empty) or an internal node (children non-empty).","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"children":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"employeeCount":{"type":"integer","format":"int32","description":"For leaf nodes: count of employees directly assigned. For internal nodes: recursive sum of descendant leaves' counts."}}}}},"paths":{"/api/v1/company/characteristics":{"get":{"tags":["characteristics-resource"],"operationId":"getCompanyCharacteristics","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SegmentDateDTO"},{"$ref":"#/components/schemas/SegmentListDTO"},{"$ref":"#/components/schemas/SegmentTreeDTO"}]}}}}}}}}}}
```

## POST /api/v1/company/characteristics

>

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"CompanySegmentDate":{"allOf":[{"$ref":"#/components/schemas/CompanySegmentBase"},{"type":"object","properties":{"ranges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRange"},"uniqueItems":true},"deletedRanges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRange"},"uniqueItems":true}}}]},"CompanySegmentBase":{"type":"object","discriminator":{"propertyName":"questionType"},"properties":{"segmentKey":{"$ref":"#/components/schemas/CompanySegmentKey"},"description":{"type":"string"},"question":{"$ref":"#/components/schemas/MultiLanguage"},"createdOn":{"type":"string","format":"date-time"},"updatedOn":{"type":"string","format":"date-time"},"coreId":{"type":"string"},"privated":{"type":"boolean"},"originalId":{"type":"string","deprecated":true},"allActiveOptionIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CompanySegmentKey":{"type":"object","properties":{"id":{"type":"string"},"companyId":{"type":"string"}}},"MultiLanguage":{"type":"object","description":"A translatable text value: a required default value plus optional per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\"). Consumers resolve the user's language from langValues (falling back to the base language, then to defaultValue).","properties":{"defaultValue":{"type":"string","description":"Fallback text used when there is no entry in langValues for the requested language.","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\")."},"valid":{"type":"boolean"}},"required":["defaultValue"]},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN","TREE"]},"CompanySegmentDateRange":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"integer","format":"int32"},"fromType":{"$ref":"#/components/schemas/DateGroupingTypes"},"to":{"type":"integer","format":"int32"},"toType":{"$ref":"#/components/schemas/DateGroupingTypes"},"name":{"type":"string"}}},"DateGroupingTypes":{"type":"string","description":"Types of date grouping intervals","enum":["DAY","WEEK","MONTH","QUARTER","NON_NATURAL_QUARTER","YEAR"]},"CompanySegmentList":{"allOf":[{"$ref":"#/components/schemas/CompanySegmentBase"},{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItem"}},"deletedValues":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItem"}}}}]},"CompanySegmentListItem":{"type":"object","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"}}},"CompanySegmentTree":{"allOf":[{"$ref":"#/components/schemas/CompanySegmentBase"},{"type":"object","properties":{"rootNodes":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentTreeNode"}},"deletedNodes":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentTreeNode"}},"allNodeIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"allLeafIds":{"type":"array","items":{"type":"string"},"uniqueItems":true}}}]},"CompanySegmentTreeNode":{"type":"object","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"children":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentTreeNode"}},"leaf":{"type":"boolean"}}},"SegmentDateDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"ranges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true},"deletedRanges":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentDateRangeDTO"},"uniqueItems":true}}}],"description":"Date-based company segment implementation","required":["questionType"]},"SegmentBaseDTO":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/SegmentListDTO","DATE":"#/components/schemas/SegmentDateDTO","TREE":"#/components/schemas/SegmentTreeDTO"}},"properties":{"id":{"type":"string"},"description":{"type":"string"},"question":{"$ref":"#/components/schemas/MultiLanguage"},"privated":{"type":"boolean"},"isCore":{"type":"boolean"},"employeeCount":{"type":"integer","format":"int32"},"core":{"type":"boolean"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}},"required":["description","questionType"]},"CompanySegmentDateRangeDTO":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"integer","format":"int32"},"fromType":{"$ref":"#/components/schemas/DateGroupingTypes"},"to":{"type":"integer","format":"int32"},"toType":{"$ref":"#/components/schemas/DateGroupingTypes"},"name":{"type":"string"},"employeeCount":{"type":"integer","format":"int32"}}},"SegmentListDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}},"deletedValues":{"type":"array","items":{"$ref":"#/components/schemas/CompanySegmentListItemDTO"}}}}],"description":"List-based company segment implementation","required":["questionType"]},"CompanySegmentListItemDTO":{"type":"object","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"employeeCount":{"type":"integer","format":"int32"}}},"SegmentTreeDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"rootNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"deletedNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}}}}],"description":"Tree-based company segment (hierarchical / N levels). Employees are assigned to leaf nodes only; filters may target any level and the server expands parent selections to descendant leaves.","required":["questionType"]},"TreeNodeDTO":{"type":"object","description":"A single node in a tree segment. May be a leaf (children empty) or an internal node (children non-empty).","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"children":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"employeeCount":{"type":"integer","format":"int32","description":"For leaf nodes: count of employees directly assigned. For internal nodes: recursive sum of descendant leaves' counts."}}}}},"paths":{"/api/v1/company/characteristics":{"post":{"tags":["characteristics-resource"],"operationId":"createCompanyCharacteristics","requestBody":{"content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CompanySegmentDate"},{"$ref":"#/components/schemas/CompanySegmentList"},{"$ref":"#/components/schemas/CompanySegmentTree"}]}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SegmentDateDTO"},{"$ref":"#/components/schemas/SegmentListDTO"},{"$ref":"#/components/schemas/SegmentTreeDTO"}]}}}}}}}}}
```

## GET /api/v1/company/characteristics/{characteristicId}/history

>

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"SegmentTreeHistoryEntryDTO":{"type":"object","description":"Summary of a single TREE segment configuration snapshot","properties":{"version":{"type":"integer","format":"int32","description":"Monotonically increasing version per segment; first snapshot is version 1."},"changedOn":{"type":"string","format":"date-time","description":"When the change was recorded."},"changedBy":{"type":"string","description":"User that performed the change; null for system-triggered changes."},"changeType":{"$ref":"#/components/schemas/SegmentTreeChangeType","description":"What caused this snapshot."},"description":{"type":"string","description":"Optional human-authored note attached to the change."}}},"SegmentTreeChangeType":{"type":"string","description":"Type of change recorded in a tree segment history snapshot","enum":["CREATE","UPDATE","NODE_DELETED","RESTORE"]}}},"paths":{"/api/v1/company/characteristics/{characteristicId}/history":{"get":{"tags":["characteristics-resource"],"operationId":"listSegmentTreeHistory","parameters":[{"name":"characteristicId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SegmentTreeHistoryEntryDTO"}}}}}}}}}}
```

## GET /api/v1/company/characteristics/{characteristicId}/history/{version}

>

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"SegmentTreeDTO":{"type":"object","allOf":[{"$ref":"#/components/schemas/SegmentBaseDTO"},{"type":"object","properties":{"rootNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"deletedNodes":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}}}}],"description":"Tree-based company segment (hierarchical / N levels). Employees are assigned to leaf nodes only; filters may target any level and the server expands parent selections to descendant leaves.","required":["questionType"]},"SegmentBaseDTO":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/SegmentListDTO","DATE":"#/components/schemas/SegmentDateDTO","TREE":"#/components/schemas/SegmentTreeDTO"}},"properties":{"id":{"type":"string"},"description":{"type":"string"},"question":{"$ref":"#/components/schemas/MultiLanguage"},"privated":{"type":"boolean"},"isCore":{"type":"boolean"},"employeeCount":{"type":"integer","format":"int32"},"core":{"type":"boolean"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}},"required":["description","questionType"]},"MultiLanguage":{"type":"object","description":"A translatable text value: a required default value plus optional per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\"). Consumers resolve the user's language from langValues (falling back to the base language, then to defaultValue).","properties":{"defaultValue":{"type":"string","description":"Fallback text used when there is no entry in langValues for the requested language.","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language overrides keyed by language tag (e.g. \"es\", \"en\", \"pt-BR\")."},"valid":{"type":"boolean"}},"required":["defaultValue"]},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN","TREE"]},"TreeNodeDTO":{"type":"object","description":"A single node in a tree segment. May be a leaf (children empty) or an internal node (children non-empty).","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/MultiLanguage"},"position":{"type":"integer","format":"int32"},"children":{"type":"array","items":{"$ref":"#/components/schemas/TreeNodeDTO"}},"employeeCount":{"type":"integer","format":"int32","description":"For leaf nodes: count of employees directly assigned. For internal nodes: recursive sum of descendant leaves' counts."}}}}},"paths":{"/api/v1/company/characteristics/{characteristicId}/history/{version}":{"get":{"tags":["characteristics-resource"],"operationId":"getSegmentTreeHistoryVersion","parameters":[{"name":"characteristicId","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/SegmentTreeDTO"}}}}}}}}}
```
