> 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/surveys.md).

# Surveys

## GET /api/v1/employee/surveys/{employeeId}/survey/{surveyRoundId}

> Get's pending survey status for a given employee

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"SurveyDTO":{"type":"object","description":"The details of the survey to be created","properties":{"id":{"type":"string"},"companyId":{"type":"string"},"createdOn":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"updatedBy":{"type":"string"},"updatedOn":{"type":"string","format":"date-time"},"managerAccessEnabled":{"type":"boolean"},"allowedViewerIds":{"type":"array","description":"Per-survey viewer allow-list: ids of the managers allowed to view this survey's results. Null/empty means every manager of the targeted area may view the results; when populated, only these managers (plus admins/advisors and the creator) may. Serialized as an array of person id strings.","items":{"type":"string"},"uniqueItems":true},"notAnonymous":{"type":"boolean"},"canUpdate":{"type":"boolean"},"canViewResults":{"type":"boolean"},"title":{"$ref":"#/components/schemas/MultiLanguage"},"description":{"$ref":"#/components/schemas/MultiLanguage"},"schedulePlan":{"$ref":"#/components/schemas/SurveySchedulePlanDTO"},"rounds":{"type":"array","items":{"$ref":"#/components/schemas/SurveyRoundDTO"}},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/SurveyBlockDTOAbstractSurveyQuestion"},"minItems":1},"status":{"$ref":"#/components/schemas/SurveyStatus"},"hasReports":{"type":"boolean"}},"required":["blocks","title"]},"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"]},"SurveySchedulePlanDTO":{"type":"object","description":"The details of the schedule to be updated","properties":{"roundTitle":{"$ref":"#/components/schemas/MultiLanguage"},"appSurvey":{"type":"boolean"},"mailSurvey":{"type":"boolean"},"communicationTitle":{"$ref":"#/components/schemas/MultiLanguage"},"communicationDescription":{"$ref":"#/components/schemas/MultiLanguage"},"activationRule":{"$ref":"#/components/schemas/ActivationRule"},"hierarchyIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueTree"}]},"uniqueItems":true},"groupIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"paused":{"type":"boolean"},"archived":{"type":"boolean"},"mandatory":{"type":"boolean"},"status":{"$ref":"#/components/schemas/SurveyStatus"}},"required":["activationRule"]},"ActivationRule":{"type":"object","description":"Base class for all activation rule types","discriminator":{"propertyName":"ruleType","mapping":{"CALENDAR":"#/components/schemas/ActivationCalendarRule","RECURRENT":"#/components/schemas/ActivationRecurrentRule","SINGLE":"#/components/schemas/ActivationSingleRule","CONTINUOUS":"#/components/schemas/ContinuousActivationRule"}},"oneOf":[{"$ref":"#/components/schemas/ActivationCalendarRule"},{"$ref":"#/components/schemas/ActivationRecurrentRule"},{"$ref":"#/components/schemas/ActivationSingleRule"},{"$ref":"#/components/schemas/ContinuousActivationRule"}],"properties":{"ruleType":{"$ref":"#/components/schemas/ActivationRuleType"}},"required":["ruleType"]},"ActivationCalendarRule":{"type":"object","allOf":[{"$ref":"#/components/schemas/ActivationRule"},{"type":"object","properties":{"ruleExpression":{"type":"string","minLength":1},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"duration":{"type":"integer","format":"int32","minimum":1}}}],"description":"ActivationCalendarRule","required":["ruleExpression","ruleType","startAt"]},"ActivationRecurrentRule":{"type":"object","allOf":[{"$ref":"#/components/schemas/ActivationRule"},{"type":"object","properties":{"cronExpression":{"type":"string","minLength":1},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"duration":{"type":"integer","format":"int32","minimum":1}}}],"description":"ActivationRecurrentRule","required":["cronExpression","ruleType","startAt"]},"ActivationSingleRule":{"type":"object","allOf":[{"$ref":"#/components/schemas/ActivationRule"},{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}}],"description":"ActivationSingleRule","required":["ruleType"]},"ContinuousActivationRule":{"type":"object","allOf":[{"$ref":"#/components/schemas/ActivationRule"}],"description":"ContinuousActivationRule","required":["ruleType"]},"ActivationRuleType":{"type":"string","description":"Type of activation rule for a survey or questionnaire","enum":["SINGLE","RECURRENT","CALENDAR","CONTINUOUS"]},"EmployeeCharacteristicValueBoolean":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"boolean"}}}]},"EmployeeCharacteristicValueBase":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/EmployeeCharacteristicValueList","DATE":"#/components/schemas/EmployeeCharacteristicValueDate","BOOLEAN":"#/components/schemas/EmployeeCharacteristicValueBoolean","TREE":"#/components/schemas/EmployeeCharacteristicValueTree"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN","TREE"]},"EmployeeCharacteristicValueDate":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"value":{"type":"string"}}}]},"EmployeeCharacteristicValueList":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"string"}}}]},"EmployeeCharacteristicValueTree":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"string"},"assignedPath":{"type":"array","items":{"type":"string"}},"assignedOn":{"type":"string","format":"date-time"}}}]},"SurveyStatus":{"type":"string","description":"Status of a survey or questionnaire","enum":["PAUSED","EXPIRED","FUTURE","NOW","ARCHIVED","DRAFT"]},"SurveyRoundDTO":{"type":"object","description":"Survey Round Data Transfer Object","properties":{"id":{"type":"string"},"title":{"$ref":"#/components/schemas/MultiLanguage"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"SurveyBlockDTOAbstractSurveyQuestion":{"type":"object","description":"A survey block containing a list of questions","properties":{"blockId":{"type":"string"},"title":{"$ref":"#/components/schemas/MultiLanguage"},"description":{"$ref":"#/components/schemas/MultiLanguage"},"questions":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/OpenSurveyQuestion"},{"$ref":"#/components/schemas/OptionsSurveyQuestion"},{"$ref":"#/components/schemas/ScaleSurveyQuestion"}]}}}},"OpenSurveyQuestion":{"allOf":[{"$ref":"#/components/schemas/AbstractSurveyQuestion"},{"type":"object","properties":{"requireNotEmpty":{"type":"boolean"}}}],"required":["questionType","representation","title","voteMode"]},"AbstractSurveyQuestion":{"type":"object","description":"Base class for survey questions","discriminator":{"propertyName":"questionType","mapping":{"OPEN":"#/components/schemas/OpenSurveyQuestion","TOPIC":"#/components/schemas/OptionsSurveyQuestion","RANGE":"#/components/schemas/ScaleSurveyQuestion"}},"properties":{"id":{"type":"string"},"title":{"$ref":"#/components/schemas/MultiLanguage"},"questionType":{"$ref":"#/components/schemas/QuestionType"},"order":{"type":"integer","format":"int32"},"visible":{"type":"boolean"},"computeInBlock":{"type":"boolean"},"feedbackEnabled":{"type":"boolean"},"mandatory":{"type":"boolean","deprecated":true},"voteMode":{"$ref":"#/components/schemas/QuestionVoteMode"},"representation":{"type":"string","enum":["IMAGES","OPTIONS","MULTIPLE_OPTIONS","FEEDBACK","SCALE","GRADIENT_SLIDE"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/QuestionValue"},"uniqueItems":true}},"required":["questionType","representation","title","voteMode"]},"QuestionType":{"type":"string","description":"Type of question used in company surveys or questionnaires","enum":["GENERAL","TOPIC","OPEN","RANGE"]},"QuestionVoteMode":{"type":"string","description":"Modes of question voting in a survey or feedback form. Defines whether a question is mandatory, optional, or deferred.","enum":["MANDATORY","OPTIONAL","DEFERRED"]},"QuestionValue":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"score":{"type":"integer","format":"int32"},"label":{"$ref":"#/components/schemas/MultiLanguage"},"imageUrl":{"type":"string"},"color":{"type":"string"}},"required":["id","label","score"]},"OptionsSurveyQuestion":{"allOf":[{"$ref":"#/components/schemas/AbstractSurveyQuestion"},{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/QuestionValue"},"maxItems":2147483647,"minItems":2,"uniqueItems":true},"minSelection":{"type":"integer","format":"int32"},"maxSelection":{"type":"integer","format":"int32"},"multipleChoice":{"type":"boolean"},"minValue":{"$ref":"#/components/schemas/QuestionValue"},"maxValue":{"$ref":"#/components/schemas/QuestionValue"}}}],"required":["questionType","representation","title","voteMode"]},"ScaleSurveyQuestion":{"allOf":[{"$ref":"#/components/schemas/AbstractSurveyQuestion"},{"type":"object","properties":{"firstValue":{"$ref":"#/components/schemas/QuestionValue"},"lastValue":{"$ref":"#/components/schemas/QuestionValue"},"inverted":{"type":"boolean"}}}],"required":["firstValue","lastValue","questionType","representation","title","voteMode"]}}},"paths":{"/api/v1/employee/surveys/{employeeId}/survey/{surveyRoundId}":{"get":{"tags":["Surveys"],"description":"Get's pending survey status for a given employee","operationId":"getSurvey_1","parameters":[{"name":"surveyRoundId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyDTO"}}}}}}}}}
```

## POST /api/v1/employee/surveys/{employeeId}/survey/{surveyRoundId}

> Post a survey answer status for a given employee

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"EmployeeVote":{"type":"object","properties":{"questionId":{"type":"string"},"selectedValue":{"type":"integer","format":"int32"},"selectedValues":{"type":"array","items":{"type":"integer","format":"int32"},"uniqueItems":true},"message":{"type":"string"},"date":{"type":"string","format":"date-time"},"feedbackType":{"$ref":"#/components/schemas/FeedbackType"},"additionalFields":{"type":"object","additionalProperties":{}},"privated":{"type":"boolean"},"notAnonymous":{"type":"boolean"}}},"FeedbackType":{"type":"string","description":"Type of feedback","enum":["RECOGNITION","CONGRATULATION","SUGGESTION","INFORMATION","CRITICISM","OTHER","SCORE","ENPS","CLASSIFICATION_FOLLOWUP","QUESTION","SURVEY","ANNOUNCEMENT_COMMENT"]}}},"paths":{"/api/v1/employee/surveys/{employeeId}/survey/{surveyRoundId}":{"post":{"tags":["Surveys"],"description":"Post a survey answer status for a given employee","operationId":"postSurveyAnswer","parameters":[{"name":"surveyRoundId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeVote"}}},"required":true},"responses":{"200":{"description":"OK"}}}}}}
```

## POST /api/v1/employee/surveys/{employeeId}/survey/{surveyRoundId}/verify

> Checks a reply for moderation before posting

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"EmployeeVote":{"type":"object","properties":{"questionId":{"type":"string"},"selectedValue":{"type":"integer","format":"int32"},"selectedValues":{"type":"array","items":{"type":"integer","format":"int32"},"uniqueItems":true},"message":{"type":"string"},"date":{"type":"string","format":"date-time"},"feedbackType":{"$ref":"#/components/schemas/FeedbackType"},"additionalFields":{"type":"object","additionalProperties":{}},"privated":{"type":"boolean"},"notAnonymous":{"type":"boolean"}}},"FeedbackType":{"type":"string","description":"Type of feedback","enum":["RECOGNITION","CONGRATULATION","SUGGESTION","INFORMATION","CRITICISM","OTHER","SCORE","ENPS","CLASSIFICATION_FOLLOWUP","QUESTION","SURVEY","ANNOUNCEMENT_COMMENT"]},"FeedbackVerificationResultDTO":{"type":"object","description":"Result of feedback verification/moderation: result type, moderation action, and optional message/suggestion.","properties":{"result":{"$ref":"#/components/schemas/VerificationResultType","description":"Verification result"},"moderationType":{"$ref":"#/components/schemas/ModerationType","description":"Moderation type applied"},"message":{"type":"string","description":"Optional message (e.g. reason for block)"},"suggestion":{"type":"string","description":"Optional suggestion for the user (e.g. when moderation type is SUGGESTION)"}}},"VerificationResultType":{"type":"string","description":"Verification outcome: VALID, INPROPER_IMAGE, INPROPER_TEXT, OTHER","enum":["VALID","INPROPER_IMAGE","INPROPER_TEXT","OTHER"]},"ModerationType":{"type":"string","description":"Moderation action: SUGGESTION (suggest change) or BLOCK","enum":["SUGGESTION","BLOCK"]}}},"paths":{"/api/v1/employee/surveys/{employeeId}/survey/{surveyRoundId}/verify":{"post":{"tags":["Surveys"],"description":"Checks a reply for moderation before posting","operationId":"verifySurveyComment_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeVote"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackVerificationResultDTO"}}}}}}}}}
```

## GET /api/v1/employee/surveys/{employeeId}/status

> Get's pending survey status for a given employee

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"SurveyPendingStatusDTO":{"type":"object","description":"Pending survey/round status: ids, title, description, dates, question counts, time, signature mode, mandatory.","properties":{"roundId":{"type":"string","description":"Survey round identifier"},"surveyId":{"type":"string","description":"Survey identifier"},"title":{"type":"string","description":"Title"},"description":{"type":"string","description":"Description"},"imagePath":{"type":"string","description":"URL or path to the image"},"endDate":{"type":"string","format":"date-time","description":"End date"},"totalQuestions":{"type":"integer","format":"int32","description":"Total number of questions"},"pendingQuestions":{"type":"integer","format":"int32","description":"Number of pending questions"},"totalTime":{"type":"integer","format":"int32","description":"Total time (e.g. in minutes)"},"signatureMode":{"$ref":"#/components/schemas/SignatureMode","description":"Signature mode"},"mandatory":{"type":"boolean","description":"Whether the survey is mandatory"}}},"SignatureMode":{"type":"string","enum":["ANONYMOUS","OPTIONAL","MANDATORY","PUBLIC_MANDATORY"]}}},"paths":{"/api/v1/employee/surveys/{employeeId}/status":{"get":{"tags":["Surveys"],"description":"Get's pending survey status for a given employee","operationId":"getSurveyStatus","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SurveyPendingStatusDTO"}}}}}}}}}}
```
