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

# Action Plans

Create and manage action plans — named containers that group improvement actions under a shared goal. Every action must belong to a plan.

## List action plans

> Returns a paginated slice of action plans, sorted newest-first. Each plan includes its actions — filtered when any filter param is set. \*\*With filters:\*\* only plans with at least one matching action are returned; each plan's \`actions\[]\` contains only matching actions; \`total\` counts matching plans. \*\*Without filters:\*\* all plans, all actions. \`from\` / \`to\` are zero-based offset / exclusive end index.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Action Plans","description":"Create and manage action plans — named containers that group improvement actions under a shared goal. Every action must belong to a plan."}],"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":{"PaginableGenericResultListActionPlanDTO":{"type":"object","properties":{"from":{"type":"integer","format":"int32"},"to":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"},"result":{"type":"array","items":{"$ref":"#/components/schemas/ActionPlanDTO"}}}},"ActionPlanDTO":{"type":"object","description":"Action plan — a named container grouping one or more improvement actions under a shared goal","properties":{"id":{"type":"string","description":"Unique plan identifier"},"companyId":{"type":"string","description":"Company that owns this plan"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the plan's goal (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed description of the plan's objective (multilingual)"},"actions":{"type":"array","description":"Actions belonging to this plan","items":{"$ref":"#/components/schemas/ActionDTO"}},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to the plan creator.","enum":["PUBLIC","PRIVATE"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of actions in this plan that have reached COMPLETED status (0–100). Computed on-the-fly; never stored."},"createdBy":{"type":"string","description":"User who created this plan"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"}}},"MultiLanguage":{"type":"object","properties":{"defaultValue":{"type":"string","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"}},"valid":{"type":"boolean"}},"required":["defaultValue"]},"ActionDTO":{"type":"object","description":"Complete action payload returned by the API","properties":{"id":{"type":"string","description":"Unique action identifier"},"companyId":{"type":"string","description":"Company that owns this action"},"planId":{"type":"string","description":"Parent action plan identifier. Null when the action is standalone."},"plan":{"$ref":"#/components/schemas/PlanSummary","description":"Lightweight plan summary (id, title, description). Null when the action is standalone."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: defaultValue = main language, langValues = translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators this action is anchored to. At least one is always present.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"assigneeStatuses":{"type":"array","description":"Per-assignee lifecycle states. Each entry tracks one manager's individual progress. The global status field is the aggregate of all entries.","items":{"$ref":"#/components/schemas/AssigneeStatusDTO"}},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueTree"}]},"uniqueItems":true},"actionType":{"type":"string","description":"Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.","enum":["MANUAL","SUGGESTION","AI"]},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.","enum":["PUBLIC","PRIVATE"]},"status":{"type":"string","description":"Aggregate lifecycle status (computed from all assignee states).","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored."},"dueDate":{"type":"string","format":"date-time","description":"Target completion date"},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the first assignee moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when all assignees reached a terminal status"},"createdBy":{"type":"string","description":"User who created this action"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"notes":{"type":"array","description":"Execution log notes (bitácora). Visibility-filtered: PRIVATE notes are only returned when the caller is the author. Not populated in list responses — only in single-action detail (GET /actions/{id}).","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"PlanSummary":{"type":"object","description":"Lightweight plan reference — id, title and description only","properties":{"id":{"type":"string","description":"Plan identifier"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan title (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan goal description (multilingual)"}}},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"AssigneeStatusDTO":{"type":"object","description":"Per-assignee lifecycle state within an action","properties":{"assigneeId":{"type":"string","description":"Assignee (manager) identifier"},"status":{"type":"string","description":"This assignee's current lifecycle status","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee first moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee reached a terminal status"}}},"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"}}}]},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/action-plans":{"get":{"tags":["Action Plans"],"summary":"List action plans","description":"Returns a paginated slice of action plans, sorted newest-first. Each plan includes its actions — filtered when any filter param is set. **With filters:** only plans with at least one matching action are returned; each plan's `actions[]` contains only matching actions; `total` counts matching plans. **Without filters:** all plans, all actions. `from` / `to` are zero-based offset / exclusive end index.","operationId":"listPlans","parameters":[{"name":"from","in":"query","description":"Zero-based start index (default 0)","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"to","in":"query","description":"Exclusive end index (default 10)","required":false,"schema":{"type":"integer","format":"int32","default":10}},{"name":"status","in":"query","description":"Filter plans whose actions have this status","required":false,"schema":{"type":"string","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]}},{"name":"focusType","in":"query","description":"Filter plans whose actions target this focus type","required":false,"schema":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]}},{"name":"hierarchyId","in":"query","description":"Filter plans whose actions target this hierarchy","required":false,"schema":{"type":"string"}},{"name":"assigneeId","in":"query","description":"Filter plans whose actions include this assignee","required":false,"schema":{"type":"string"}},{"name":"actionType","in":"query","description":"Filter plans whose actions target this action type","required":false,"schema":{"type":"string","enum":["MANAGER","COMPANY"]}},{"name":"q","in":"query","description":"Free-text search on action title and description (case-insensitive contains)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated plan list, each with their (filtered) actions","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaginableGenericResultListActionPlanDTO"}}}}}}}}}
```

## Create a new action plan

> Creates an empty action plan. Once created, actions can be added by creating them with the plan's ID.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Action Plans","description":"Create and manage action plans — named containers that group improvement actions under a shared goal. Every action must belong to a plan."}],"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":{"CreateActionPlanRequestDTO":{"type":"object","description":"Request payload for creating a new action plan","properties":{"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the plan's goal (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed description of the plan's objective (multilingual)"},"visibility":{"type":"string","description":"Visibility for the plan. Defaults to PRIVATE when omitted.","enum":["PUBLIC","PRIVATE"]}},"required":["description","title"]},"MultiLanguage":{"type":"object","properties":{"defaultValue":{"type":"string","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"}},"valid":{"type":"boolean"}},"required":["defaultValue"]},"ActionPlanDTO":{"type":"object","description":"Action plan — a named container grouping one or more improvement actions under a shared goal","properties":{"id":{"type":"string","description":"Unique plan identifier"},"companyId":{"type":"string","description":"Company that owns this plan"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the plan's goal (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed description of the plan's objective (multilingual)"},"actions":{"type":"array","description":"Actions belonging to this plan","items":{"$ref":"#/components/schemas/ActionDTO"}},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to the plan creator.","enum":["PUBLIC","PRIVATE"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of actions in this plan that have reached COMPLETED status (0–100). Computed on-the-fly; never stored."},"createdBy":{"type":"string","description":"User who created this plan"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"}}},"ActionDTO":{"type":"object","description":"Complete action payload returned by the API","properties":{"id":{"type":"string","description":"Unique action identifier"},"companyId":{"type":"string","description":"Company that owns this action"},"planId":{"type":"string","description":"Parent action plan identifier. Null when the action is standalone."},"plan":{"$ref":"#/components/schemas/PlanSummary","description":"Lightweight plan summary (id, title, description). Null when the action is standalone."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: defaultValue = main language, langValues = translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators this action is anchored to. At least one is always present.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"assigneeStatuses":{"type":"array","description":"Per-assignee lifecycle states. Each entry tracks one manager's individual progress. The global status field is the aggregate of all entries.","items":{"$ref":"#/components/schemas/AssigneeStatusDTO"}},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueTree"}]},"uniqueItems":true},"actionType":{"type":"string","description":"Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.","enum":["MANUAL","SUGGESTION","AI"]},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.","enum":["PUBLIC","PRIVATE"]},"status":{"type":"string","description":"Aggregate lifecycle status (computed from all assignee states).","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored."},"dueDate":{"type":"string","format":"date-time","description":"Target completion date"},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the first assignee moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when all assignees reached a terminal status"},"createdBy":{"type":"string","description":"User who created this action"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"notes":{"type":"array","description":"Execution log notes (bitácora). Visibility-filtered: PRIVATE notes are only returned when the caller is the author. Not populated in list responses — only in single-action detail (GET /actions/{id}).","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"PlanSummary":{"type":"object","description":"Lightweight plan reference — id, title and description only","properties":{"id":{"type":"string","description":"Plan identifier"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan title (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan goal description (multilingual)"}}},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"AssigneeStatusDTO":{"type":"object","description":"Per-assignee lifecycle state within an action","properties":{"assigneeId":{"type":"string","description":"Assignee (manager) identifier"},"status":{"type":"string","description":"This assignee's current lifecycle status","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee first moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee reached a terminal status"}}},"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"}}}]},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/action-plans":{"post":{"tags":["Action Plans"],"summary":"Create a new action plan","description":"Creates an empty action plan. Once created, actions can be added by creating them with the plan's ID.","operationId":"createPlan","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/CreateActionPlanRequestDTO"}}},"required":true},"responses":{"200":{"description":"Plan created successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionPlanDTO"}}}},"400":{"description":"Validation failed: missing title or description","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionPlanDTO"}}}}}}}}}
```

## Export action plan to Excel

> Triggers an asynchronous Excel export of this action plan. The workbook contains a summary sheet followed by one sheet per action. The file will be delivered to your e-mail address as a time-limited download link. The response is empty — the file arrives via e-mail within seconds.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Action Plans","description":"Create and manage action plans — named containers that group improvement actions under a shared goal. Every action must belong to a plan."}],"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"}}},"paths":{"/api/v1/company/action-plans/{planId}/excel":{"post":{"tags":["Action Plans"],"summary":"Export action plan to Excel","description":"Triggers an asynchronous Excel export of this action plan. The workbook contains a summary sheet followed by one sheet per action. The file will be delivered to your e-mail address as a time-limited download link. The response is empty — the file arrives via e-mail within seconds.","operationId":"exportPlanToExcel","parameters":[{"name":"planId","in":"path","description":"Plan identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Export triggered — file will be sent by e-mail"}}}}}}
```

## Get action plan details

> Returns the full action plan with its actions.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Action Plans","description":"Create and manage action plans — named containers that group improvement actions under a shared goal. Every action must belong to a plan."}],"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":{"ActionPlanDTO":{"type":"object","description":"Action plan — a named container grouping one or more improvement actions under a shared goal","properties":{"id":{"type":"string","description":"Unique plan identifier"},"companyId":{"type":"string","description":"Company that owns this plan"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the plan's goal (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed description of the plan's objective (multilingual)"},"actions":{"type":"array","description":"Actions belonging to this plan","items":{"$ref":"#/components/schemas/ActionDTO"}},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to the plan creator.","enum":["PUBLIC","PRIVATE"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of actions in this plan that have reached COMPLETED status (0–100). Computed on-the-fly; never stored."},"createdBy":{"type":"string","description":"User who created this plan"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"}}},"MultiLanguage":{"type":"object","properties":{"defaultValue":{"type":"string","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"}},"valid":{"type":"boolean"}},"required":["defaultValue"]},"ActionDTO":{"type":"object","description":"Complete action payload returned by the API","properties":{"id":{"type":"string","description":"Unique action identifier"},"companyId":{"type":"string","description":"Company that owns this action"},"planId":{"type":"string","description":"Parent action plan identifier. Null when the action is standalone."},"plan":{"$ref":"#/components/schemas/PlanSummary","description":"Lightweight plan summary (id, title, description). Null when the action is standalone."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: defaultValue = main language, langValues = translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators this action is anchored to. At least one is always present.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"assigneeStatuses":{"type":"array","description":"Per-assignee lifecycle states. Each entry tracks one manager's individual progress. The global status field is the aggregate of all entries.","items":{"$ref":"#/components/schemas/AssigneeStatusDTO"}},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueTree"}]},"uniqueItems":true},"actionType":{"type":"string","description":"Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.","enum":["MANUAL","SUGGESTION","AI"]},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.","enum":["PUBLIC","PRIVATE"]},"status":{"type":"string","description":"Aggregate lifecycle status (computed from all assignee states).","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored."},"dueDate":{"type":"string","format":"date-time","description":"Target completion date"},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the first assignee moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when all assignees reached a terminal status"},"createdBy":{"type":"string","description":"User who created this action"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"notes":{"type":"array","description":"Execution log notes (bitácora). Visibility-filtered: PRIVATE notes are only returned when the caller is the author. Not populated in list responses — only in single-action detail (GET /actions/{id}).","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"PlanSummary":{"type":"object","description":"Lightweight plan reference — id, title and description only","properties":{"id":{"type":"string","description":"Plan identifier"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan title (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan goal description (multilingual)"}}},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"AssigneeStatusDTO":{"type":"object","description":"Per-assignee lifecycle state within an action","properties":{"assigneeId":{"type":"string","description":"Assignee (manager) identifier"},"status":{"type":"string","description":"This assignee's current lifecycle status","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee first moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee reached a terminal status"}}},"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"}}}]},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/action-plans/{planId}":{"get":{"tags":["Action Plans"],"summary":"Get action plan details","description":"Returns the full action plan with its actions.","operationId":"getPlan","parameters":[{"name":"planId","in":"path","description":"Plan identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Plan found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionPlanDTO"}}}},"404":{"description":"Plan not found in this company","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionPlanDTO"}}}}}}}}}
```

## Delete an action plan

> Permanently removes an action plan \*\*and all of its actions\*\* (cascade delete). Only the plan creator or an admin can delete; legacy plans without a recorded creator are deletable by any authorised caller. Returns 204 on success, 403 when the caller is not allowed, 404 when not found.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Action Plans","description":"Create and manage action plans — named containers that group improvement actions under a shared goal. Every action must belong to a plan."}],"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"}}},"paths":{"/api/v1/company/action-plans/{planId}":{"delete":{"tags":["Action Plans"],"summary":"Delete an action plan","description":"Permanently removes an action plan **and all of its actions** (cascade delete). Only the plan creator or an admin can delete; legacy plans without a recorded creator are deletable by any authorised caller. Returns 204 on success, 403 when the caller is not allowed, 404 when not found.","operationId":"deletePlan","parameters":[{"name":"planId","in":"path","description":"Plan identifier","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Plan and all its actions deleted"},"403":{"description":"Caller is not the creator or an admin"},"404":{"description":"Plan not found in this company"}}}}}}
```

## Update action plan

> Applies a partial update to an action plan. Only non-null fields are updated.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Action Plans","description":"Create and manage action plans — named containers that group improvement actions under a shared goal. Every action must belong to a plan."}],"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":{"UpdateActionPlanRequestDTO":{"type":"object","description":"Request payload for updating an action plan. Only non-null fields are applied.","properties":{"title":{"$ref":"#/components/schemas/MultiLanguage","description":"New title for the plan (multilingual, null = no change)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"New description for the plan (multilingual, null = no change)"},"visibility":{"type":"string","description":"New visibility. Null means no change.","enum":["PUBLIC","PRIVATE"]}}},"MultiLanguage":{"type":"object","properties":{"defaultValue":{"type":"string","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"}},"valid":{"type":"boolean"}},"required":["defaultValue"]},"ActionPlanDTO":{"type":"object","description":"Action plan — a named container grouping one or more improvement actions under a shared goal","properties":{"id":{"type":"string","description":"Unique plan identifier"},"companyId":{"type":"string","description":"Company that owns this plan"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the plan's goal (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed description of the plan's objective (multilingual)"},"actions":{"type":"array","description":"Actions belonging to this plan","items":{"$ref":"#/components/schemas/ActionDTO"}},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to the plan creator.","enum":["PUBLIC","PRIVATE"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of actions in this plan that have reached COMPLETED status (0–100). Computed on-the-fly; never stored."},"createdBy":{"type":"string","description":"User who created this plan"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"}}},"ActionDTO":{"type":"object","description":"Complete action payload returned by the API","properties":{"id":{"type":"string","description":"Unique action identifier"},"companyId":{"type":"string","description":"Company that owns this action"},"planId":{"type":"string","description":"Parent action plan identifier. Null when the action is standalone."},"plan":{"$ref":"#/components/schemas/PlanSummary","description":"Lightweight plan summary (id, title, description). Null when the action is standalone."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: defaultValue = main language, langValues = translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators this action is anchored to. At least one is always present.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"assigneeStatuses":{"type":"array","description":"Per-assignee lifecycle states. Each entry tracks one manager's individual progress. The global status field is the aggregate of all entries.","items":{"$ref":"#/components/schemas/AssigneeStatusDTO"}},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueTree"}]},"uniqueItems":true},"actionType":{"type":"string","description":"Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.","enum":["MANUAL","SUGGESTION","AI"]},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.","enum":["PUBLIC","PRIVATE"]},"status":{"type":"string","description":"Aggregate lifecycle status (computed from all assignee states).","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored."},"dueDate":{"type":"string","format":"date-time","description":"Target completion date"},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the first assignee moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when all assignees reached a terminal status"},"createdBy":{"type":"string","description":"User who created this action"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"notes":{"type":"array","description":"Execution log notes (bitácora). Visibility-filtered: PRIVATE notes are only returned when the caller is the author. Not populated in list responses — only in single-action detail (GET /actions/{id}).","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"PlanSummary":{"type":"object","description":"Lightweight plan reference — id, title and description only","properties":{"id":{"type":"string","description":"Plan identifier"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan title (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan goal description (multilingual)"}}},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"AssigneeStatusDTO":{"type":"object","description":"Per-assignee lifecycle state within an action","properties":{"assigneeId":{"type":"string","description":"Assignee (manager) identifier"},"status":{"type":"string","description":"This assignee's current lifecycle status","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee first moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee reached a terminal status"}}},"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"}}}]},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/action-plans/{planId}":{"patch":{"tags":["Action Plans"],"summary":"Update action plan","description":"Applies a partial update to an action plan. Only non-null fields are updated.","operationId":"updatePlan","parameters":[{"name":"planId","in":"path","description":"Plan identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/UpdateActionPlanRequestDTO"}}},"required":true},"responses":{"200":{"description":"Plan updated successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionPlanDTO"}}}},"400":{"description":"No updatable fields provided, or plan not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionPlanDTO"}}}},"404":{"description":"Plan not found in this company","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionPlanDTO"}}}}}}}}}
```