> 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"}]},"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"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN"]},"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"}}}]},"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"}]},"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"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN"]},"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"}}}]},"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"}]},"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"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN"]},"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"}}}]},"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"}]},"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"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN"]},"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"}}}]},"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"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.myhappyforce.com/docs/api-reference/action-plans.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.