Actions

Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora).

List actions

get

Returns all actions for the authenticated company, sorted from newest to oldest. Overdue in-progress actions are expired on-the-fly before the result is returned. All filter parameters are optional and combinable. Use planId to scope results to a specific plan, or omit it to return all actions.

Authorizations

SessionIdstringRequired

SessionId

Query parameters

planIdstringOptional

Filter by parent action plan (omit to return all actions regardless of plan)

Example: 64f8a0e2d5b7c9a1e3f4a5b6

hierarchyIdstringOptional

Filter by area/hierarchy (matches any entry in the action's hierarchyIds)

Example: 64f8a0e2d5b7c9a1e3f4a5b6

assigneeIdstringOptional

Filter by assignee (matches any entry in the assignees list)

Example: 64f8a0e2d5b7c9a1e3f4a5b6

statusstring · enumOptional

Status filter

Possible values:

focusTypestring · enumOptional

Focus type filter (matches any focusItems entry)

Possible values:

actionTypestring · enumOptional

Action type filter

Possible values:

qstringOptional

Free-text search on action title and description (case-insensitive contains)

Responses

200

Actions returned (empty list when none match the filters)

*/*

Complete action payload returned by the API

idstringOptional

Unique action identifier

Example: 507f1f77bcf86cd799439011

companyIdstringOptional

Company that owns this action

Example: 507f1f77bcf86cd799439010

planIdstringOptional

Parent action plan identifier. Every action belongs to a plan.

Example: 507f1f77bcf86cd799439013

hierarchyIdsstring[]Optional

Areas/hierarchies this action targets. Empty means company-wide scope.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

groupIdsstring[]Optional

Groups this action targets.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

actionTypestring · enumOptional

Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.

Example: MANAGERPossible values:

sourcestring · enumOptional

How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.

Example: MANUALPossible values:

visibilitystring · enumOptional

Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.

Example: PRIVATEPossible values:

statusstring · enumOptional

Aggregate lifecycle status (computed from all assignee states).

Example: IN_PROGRESSPossible values:

completionPercentinteger · int32Optional

Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored.

Example: 50

dueDatestring · date-timeOptional

Target completion date

Example: 2025-06-30T23:59:59.000Z

startedAtstring · date-timeOptional

Timestamp when the first assignee moved to IN_PROGRESS

completedAtstring · date-timeOptional

Timestamp when all assignees reached a terminal status

createdBystringOptional

User who created this action

Example: 507f1f77bcf86cd799439012

createdAtstring · date-timeOptional

Creation timestamp

updatedAtstring · date-timeOptional

Last modification timestamp

get/api/v1/company/actions

GET /api/v1/company/actions HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Accept: */*

200

Actions returned (empty list when none match the filters)

[
  {
    "id": "507f1f77bcf86cd799439011",
    "companyId": "507f1f77bcf86cd799439010",
    "planId": "507f1f77bcf86cd799439013",
    "plan": {
      "id": "507f1f77bcf86cd799439013",
      "title": {
        "defaultValue": "Happy birthday!",
        "langValues": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "valid": true
      },
      "description": {
        "defaultValue": "Happy birthday!",
        "langValues": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "valid": true
      }
    },
    "title": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    },
    "description": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    },
    "focusItems": [
      {
        "focusType": "SCORE",
        "focusId": "text",
        "targetValue": 1,
        "targetTimestamp": "2026-01-01T00:00:00.000Z"
      }
    ],
    "assigneeStatuses": [
      {
        "assigneeId": "507f1f77bcf86cd799439011",
        "status": "IN_PROGRESS",
        "startedAt": "2026-01-01T00:00:00.000Z",
        "completedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "hierarchyIds": [
      "64f8a0e2d5b7c9a1e3f4a5b6"
    ],
    "groupIds": [
      "64f8a0e2d5b7c9a1e3f4a5b6"
    ],
    "characteristics": [
      {
        "characteristicId": "64f8a0e2d5b7c9a1e3f4a5b6",
        "id": "64f8a0e2d5b7c9a1e3f4a5b6",
        "questionType": "DATE",
        "value": true
      }
    ],
    "actionType": "MANAGER",
    "source": "MANUAL",
    "visibility": "PRIVATE",
    "status": "IN_PROGRESS",
    "completionPercent": 50,
    "dueDate": "2025-06-30T23:59:59.000Z",
    "startedAt": "2026-01-01T00:00:00.000Z",
    "completedAt": "2026-01-01T00:00:00.000Z",
    "createdBy": "507f1f77bcf86cd799439012",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "notes": [
      {
        "id": "507f1f77bcf86cd799439020",
        "authorId": "507f1f77bcf86cd799439015",
        "content": "Feedback de la retro mejoró tras introducir los reconocimientos entre pares.",
        "visibility": "SHARED",
        "createdAt": "2026-01-01T00:00:00.000Z"
      }
    ]
  }
]

Create a new action

post

Creates an action in DRAFT status anchored to one or more focus indicators. For MANAGER actions, assignees defaults to the authenticated user when omitted. For COMPANY actions, an explicit list of co-responsible manager IDs must be supplied.

Authorizations

SessionIdstringRequired

SessionId

Body

Request payload for creating a new action

planIdstringRequired

Parent action plan this action belongs to. Required — every action belongs to a plan.

Example: 507f1f77bcf86cd799439013

hierarchyIdsstring[]Optional

Areas/hierarchies this action targets. Empty or omitted means company-wide scope.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

groupIdsstring[]Optional

Groups this action targets. Optional.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

assigneesstring[]Optional

Responsible manager IDs. For MANAGER actions, defaults to the authenticated user when omitted. For COMPANY actions, provide the list of co-responsible managers.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

dueDatestring · date-timeRequired

Expected completion date. Must be in the future.

Example: 2025-06-30T23:59:59.000Z

actionTypestring · enumRequired

Scope of the action. Use MANAGER for individual manager actions, COMPANY for cross-team initiatives.

Example: MANAGERPossible values:

sourcestring · enumOptional

How the action was originated. Defaults to MANUAL when omitted.

Example: MANUALPossible values:

sourceTemplateIdstringOptional

Template this action was created from. Provide when source=TEMPLATE.

Example: 507f1f77bcf86cd799439020

visibilitystring · enumOptional

Visibility for the action. Defaults to PRIVATE when omitted.

Possible values:

Responses

200

Action created successfully

*/*

Complete action payload returned by the API

idstringOptional

Unique action identifier

Example: 507f1f77bcf86cd799439011

companyIdstringOptional

Company that owns this action

Example: 507f1f77bcf86cd799439010

planIdstringOptional

Parent action plan identifier. Every action belongs to a plan.

Example: 507f1f77bcf86cd799439013

hierarchyIdsstring[]Optional

Areas/hierarchies this action targets. Empty means company-wide scope.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

groupIdsstring[]Optional

Groups this action targets.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

actionTypestring · enumOptional

Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.

Example: MANAGERPossible values:

sourcestring · enumOptional

How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.

Example: MANUALPossible values:

visibilitystring · enumOptional

Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.

Example: PRIVATEPossible values:

statusstring · enumOptional

Aggregate lifecycle status (computed from all assignee states).

Example: IN_PROGRESSPossible values:

completionPercentinteger · int32Optional

Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored.

Example: 50

dueDatestring · date-timeOptional

Target completion date

Example: 2025-06-30T23:59:59.000Z

startedAtstring · date-timeOptional

Timestamp when the first assignee moved to IN_PROGRESS

completedAtstring · date-timeOptional

Timestamp when all assignees reached a terminal status

createdBystringOptional

User who created this action

Example: 507f1f77bcf86cd799439012

createdAtstring · date-timeOptional

Creation timestamp

updatedAtstring · date-timeOptional

Last modification timestamp

400

Validation failed: missing required fields, empty focusItems, empty assignees, or invalid actionType

*/*

post/api/v1/company/actions

POST /api/v1/company/actions HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 772

{
  "planId": "507f1f77bcf86cd799439013",
  "title": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "description": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "focusItems": [
    {
      "focusType": "SCORE",
      "focusId": "text",
      "targetValue": 1,
      "targetTimestamp": "2026-01-01T00:00:00.000Z"
    }
  ],
  "hierarchyIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "groupIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "characteristics": [
    {
      "characteristicId": "64f8a0e2d5b7c9a1e3f4a5b6",
      "id": "64f8a0e2d5b7c9a1e3f4a5b6",
      "questionType": "DATE",
      "value": true
    }
  ],
  "assignees": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "dueDate": "2025-06-30T23:59:59.000Z",
  "actionType": "MANAGER",
  "source": "MANUAL",
  "sourceTemplateId": "507f1f77bcf86cd799439020",
  "visibility": "PUBLIC"
}

{
  "id": "507f1f77bcf86cd799439011",
  "companyId": "507f1f77bcf86cd799439010",
  "planId": "507f1f77bcf86cd799439013",
  "plan": {
    "id": "507f1f77bcf86cd799439013",
    "title": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    },
    "description": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    }
  },
  "title": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "description": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "focusItems": [
    {
      "focusType": "SCORE",
      "focusId": "text",
      "targetValue": 1,
      "targetTimestamp": "2026-01-01T00:00:00.000Z"
    }
  ],
  "assigneeStatuses": [
    {
      "assigneeId": "507f1f77bcf86cd799439011",
      "status": "IN_PROGRESS",
      "startedAt": "2026-01-01T00:00:00.000Z",
      "completedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "hierarchyIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "groupIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "characteristics": [
    {
      "characteristicId": "64f8a0e2d5b7c9a1e3f4a5b6",
      "id": "64f8a0e2d5b7c9a1e3f4a5b6",
      "questionType": "DATE",
      "value": true
    }
  ],
  "actionType": "MANAGER",
  "source": "MANUAL",
  "visibility": "PRIVATE",
  "status": "IN_PROGRESS",
  "completionPercent": 50,
  "dueDate": "2025-06-30T23:59:59.000Z",
  "startedAt": "2026-01-01T00:00:00.000Z",
  "completedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "507f1f77bcf86cd799439012",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "notes": [
    {
      "id": "507f1f77bcf86cd799439020",
      "authorId": "507f1f77bcf86cd799439015",
      "content": "Feedback de la retro mejoró tras introducir los reconocimientos entre pares.",
      "visibility": "SHARED",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Change action lifecycle status

post

Applies a lifecycle transition. Allowed transitions: DRAFT→IN_PROGRESS, IN_PROGRESS→COMPLETED|PARTIALLY_COMPLETED|FAILED. The EXPIRED status is set automatically by the system and cannot be requested. Transitioning to IN_PROGRESS records startedAt; transitioning to a terminal status records completedAt.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

actionIdstringRequired

Action identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Body

Request payload to apply a lifecycle transition to an action

statusstring · enumRequired

Target lifecycle status. Only the transitions described above are allowed.

Example: IN_PROGRESSPossible values:

Responses

200

Status changed successfully

*/*

Complete action payload returned by the API

idstringOptional

Unique action identifier

Example: 507f1f77bcf86cd799439011

companyIdstringOptional

Company that owns this action

Example: 507f1f77bcf86cd799439010

planIdstringOptional

Parent action plan identifier. Every action belongs to a plan.

Example: 507f1f77bcf86cd799439013

hierarchyIdsstring[]Optional

Areas/hierarchies this action targets. Empty means company-wide scope.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

groupIdsstring[]Optional

Groups this action targets.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

actionTypestring · enumOptional

Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.

Example: MANAGERPossible values:

sourcestring · enumOptional

How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.

Example: MANUALPossible values:

visibilitystring · enumOptional

Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.

Example: PRIVATEPossible values:

statusstring · enumOptional

Aggregate lifecycle status (computed from all assignee states).

Example: IN_PROGRESSPossible values:

completionPercentinteger · int32Optional

Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored.

Example: 50

dueDatestring · date-timeOptional

Target completion date

Example: 2025-06-30T23:59:59.000Z

startedAtstring · date-timeOptional

Timestamp when the first assignee moved to IN_PROGRESS

completedAtstring · date-timeOptional

Timestamp when all assignees reached a terminal status

createdBystringOptional

User who created this action

Example: 507f1f77bcf86cd799439012

createdAtstring · date-timeOptional

Creation timestamp

updatedAtstring · date-timeOptional

Last modification timestamp

400

Transition not allowed from the current status, or status value is invalid

*/*

404

Action not found in this company

*/*

post/api/v1/company/actions/{actionId}/status

POST /api/v1/company/actions/{actionId}/status HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 24

{
  "status": "IN_PROGRESS"
}

{
  "id": "507f1f77bcf86cd799439011",
  "companyId": "507f1f77bcf86cd799439010",
  "planId": "507f1f77bcf86cd799439013",
  "plan": {
    "id": "507f1f77bcf86cd799439013",
    "title": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    },
    "description": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    }
  },
  "title": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "description": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "focusItems": [
    {
      "focusType": "SCORE",
      "focusId": "text",
      "targetValue": 1,
      "targetTimestamp": "2026-01-01T00:00:00.000Z"
    }
  ],
  "assigneeStatuses": [
    {
      "assigneeId": "507f1f77bcf86cd799439011",
      "status": "IN_PROGRESS",
      "startedAt": "2026-01-01T00:00:00.000Z",
      "completedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "hierarchyIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "groupIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "characteristics": [
    {
      "characteristicId": "64f8a0e2d5b7c9a1e3f4a5b6",
      "id": "64f8a0e2d5b7c9a1e3f4a5b6",
      "questionType": "DATE",
      "value": true
    }
  ],
  "actionType": "MANAGER",
  "source": "MANUAL",
  "visibility": "PRIVATE",
  "status": "IN_PROGRESS",
  "completionPercent": 50,
  "dueDate": "2025-06-30T23:59:59.000Z",
  "startedAt": "2026-01-01T00:00:00.000Z",
  "completedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "507f1f77bcf86cd799439012",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "notes": [
    {
      "id": "507f1f77bcf86cd799439020",
      "authorId": "507f1f77bcf86cd799439015",
      "content": "Feedback de la retro mejoró tras introducir los reconocimientos entre pares.",
      "visibility": "SHARED",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

List action notes (paginated)

get

Returns a paginated slice of the execution log for an action, ordered by creation date ascending (oldest first). Only notes visible to the caller are counted and returned: admins see all notes; managers see shared notes plus their own private ones. from / to are zero-based offset / exclusive end index applied after the visibility filter.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

actionIdstringRequired

Action identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Query parameters

frominteger · int32Optional

Zero-based start index (default 0)

Default: 0

tointeger · int32Optional

Exclusive end index (default 20)

Default: 20

Responses

200

Notes page returned (empty result when none match)

*/*

frominteger · int32Optional

tointeger · int64Optional

totalinteger · int64Optional

404

Action not found in this company

*/*

get/api/v1/company/actions/{actionId}/notes

GET /api/v1/company/actions/{actionId}/notes HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Accept: */*

{
  "from": 1,
  "to": 1,
  "total": 1,
  "result": [
    {
      "id": "507f1f77bcf86cd799439020",
      "authorId": "507f1f77bcf86cd799439015",
      "content": "Feedback de la retro mejoró tras introducir los reconocimientos entre pares.",
      "visibility": "SHARED",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Add a note to the action log

post

Appends a note to the action execution log (bitácora). The author is always the authenticated user. Notes with PRIVATE visibility are only visible to their author; SHARED notes are visible to all action participants.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

actionIdstringRequired

Action identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Body

Request payload to append a note to the action execution log

contentstring · min: 1Required

Note body text describing progress, blockers or context updates

Example: El feedback de la retro mejoró notablemente tras introducir los reconocimientos entre pares.

visibilitystring · enumOptional

Who can see this note. PRIVATE = only the author; SHARED = all action participants. Defaults to PRIVATE.

Example: PRIVATEPossible values:

Responses

200

Note created and returned

*/*

A single note appended to the action execution log

idstringOptional

Note identifier (unique within the parent action)

Example: 507f1f77bcf86cd799439020

authorIdstringOptional

User who wrote the note

Example: 507f1f77bcf86cd799439015

contentstringOptional

Note body text

Example: Feedback de la retro mejoró tras introducir los reconocimientos entre pares.

visibilitystring · enumOptional

Who can see this note. PRIVATE = only the author; SHARED = all action participants.

Example: SHAREDPossible values:

createdAtstring · date-timeOptional

Creation timestamp

400

Content is blank or action not found

*/*

404

Action not found in this company

*/*

post/api/v1/company/actions/{actionId}/notes

POST /api/v1/company/actions/{actionId}/notes HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 130

{
  "content": "El feedback de la retro mejoró notablemente tras introducir los reconocimientos entre pares.",
  "visibility": "PRIVATE"
}

{
  "id": "507f1f77bcf86cd799439020",
  "authorId": "507f1f77bcf86cd799439015",
  "content": "Feedback de la retro mejoró tras introducir los reconocimientos entre pares.",
  "visibility": "SHARED",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Trigger impact capture for a closed action

post

Manually triggers the closure snapshot capture for an action that was closed before the impact measurement feature was deployed (backfill). This is idempotent: calling it on an action that already has an impact document is a no-op. Requires the action to be in a terminal status (COMPLETED, PARTIALLY_COMPLETED or FAILED).

Authorizations

SessionIdstringRequired

SessionId

Path parameters

actionIdstringRequired

Action identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Responses

200

Capture triggered (or was already present — idempotent)

No content

400

Action not found or not in a terminal status

post/api/v1/company/actions/{actionId}/impact/capture

POST /api/v1/company/actions/{actionId}/impact/capture HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Accept: */*

No content

Export action to Excel

post

Triggers an asynchronous Excel export of this action. The workbook will be delivered to your e-mail address as a download link. The response is empty — the file arrives via e-mail within seconds.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

actionIdstringRequired

Action identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Responses

200

Export triggered — file will be sent by e-mail

No content

post/api/v1/company/actions/{actionId}/excel

POST /api/v1/company/actions/{actionId}/excel HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Accept: */*

200

Export triggered — file will be sent by e-mail

No content

Generate AI action suggestions

post

Analyses engagement score data for the requested period and returns up to 3 ready-to-use action suggestions generated by the AI. Each suggestion includes a fully populated title, description, focus indicators, scope (actionType), suggested due date and a rationale explaining the recommendation.

Date window: controlled by from/to in the request body — defaults to the last 30 days when omitted.

Team scope: when teamId is provided, metric queries are filtered to that team's hierarchy so the AI reasons about team-specific data rather than company-wide averages.

Context hint: free-text field for situation context (e.g. "Two people left last month").

The client can send the suggestion directly to the create-action endpoint (POST /v1/company/actions) with source=AI after the user confirms or adjusts the fields. Note: this call invokes an external LLM and may take a few seconds.

Authorizations

SessionIdstringRequired

SessionId

Body

Optional parameters that narrow the AI action suggestion context

teamIdstringOptional

Restrict score analysis to a specific team/hierarchy. When omitted, company-wide data is used.

Example: 507f1f77bcf86cd799439012

fromstring · date-timeOptional

Start of the measurement window (inclusive). When omitted, defaults to 30 days before 'to' (or before now if 'to' is also omitted).

Example: 2025-03-01T00:00:00.000Z

tostring · date-timeOptional

End of the measurement window (inclusive). Defaults to the current date/time when omitted.

Example: 2025-05-31T23:59:59.000Z

hintstringOptional

Free-text hint that gives the AI additional context about the current situation. Max 500 characters.

Example: Our team had two people leave last month and morale seems low.

languagestringOptional

BCP-47 language code for the suggestion text. Defaults to 'es' when omitted.

Default: esExample: es

Responses

200

Suggestions generated (may be an empty list if no engagement data is available)

*/*

AI-generated action suggestion — all fields pre-filled and ready for user review. Can be forwarded directly to POST /v1/company/actions after confirmation.

titlestringOptional

Short title describing the suggested action

Example: Implementar rituales de reconocimiento semanales

descriptionstringOptional

Detailed execution plan: how, when, and why this action addresses the focus indicator

Example: Cada viernes dedicar 10 minutos al inicio del standup a reconocer un logro concreto de un miembro del equipo.

actionTypestring · enumOptional

Recommended action scope. MANAGER for individual-team actions; COMPANY for cross-team initiatives.

Example: MANAGERPossible values:

dueDatestring · date-timeOptional

Suggested target completion date. Map this directly to the dueDate field when creating the action.

Example: 2025-09-01T00:00:00.000Z

hierarchyIdsstring[]Optional

Areas/hierarchies this action is pre-scoped to. Pre-populated from the teamId in the suggestion request; empty for company-wide suggestions.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

assigneesstring[]Optional

Responsible managers. Empty — must be filled by the user before confirming.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

currentValuenumber · doubleOptional

Current measured value of the focus indicator at the time the suggestion was generated. Provides context to show the user the baseline the action targets (e.g. 4.3 for a score on a 0–10 scale, or 62 for HI on a 0–100 scale). Null when the measurement was unavailable for the requested period.

rationalestringOptional

Brief explanation of why the model recommends this action, based on the data analysed.

Example: El factor Reconocimiento lleva 3 pulsos consecutivos con valores inferiores a 5, lo que suele correlacionar con mayor rotación.

sourcestring · enumOptional

Always AI for suggestions generated by this endpoint.

Example: AIPossible values:

400

Request validation failed

*/*

500

AI service unavailable or returned an unparseable response

*/*

post/api/v1/company/actions/suggest

POST /api/v1/company/actions/suggest HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 191

{
  "teamId": "507f1f77bcf86cd799439012",
  "from": "2025-03-01T00:00:00.000Z",
  "to": "2025-05-31T23:59:59.000Z",
  "hint": "Our team had two people leave last month and morale seems low.",
  "language": "es"
}

[
  {
    "title": "Implementar rituales de reconocimiento semanales",
    "description": "Cada viernes dedicar 10 minutos al inicio del standup a reconocer un logro concreto de un miembro del equipo.",
    "focusItems": [
      {
        "focusType": "SCORE",
        "focusId": "text",
        "targetValue": 1,
        "targetTimestamp": "2026-01-01T00:00:00.000Z"
      }
    ],
    "actionType": "MANAGER",
    "dueDate": "2025-09-01T00:00:00.000Z",
    "hierarchyIds": [
      "64f8a0e2d5b7c9a1e3f4a5b6"
    ],
    "assignees": [
      "64f8a0e2d5b7c9a1e3f4a5b6"
    ],
    "currentValue": 1,
    "rationale": "El factor Reconocimiento lleva 3 pulsos consecutivos con valores inferiores a 5, lo que suele correlacionar con mayor rotación.",
    "source": "AI"
  }
]

Deprecated

Generate an action from an employee idea

post

Deprecated — use POST /v1/company/actions/ai/from-comment/{commentId} (IA #5) instead. That endpoint returns a full plan draft (plan + its actions) from the same comment, which fits the model where every action belongs to a plan. This endpoint returns a single standalone action suggestion and is kept only for backward compatibility.

Converts an employee comment (idea or suggestion) into a single ready-to-use action. The original comment text is preserved as the seed for the action description — the AI polishes it into professional language while keeping the employee's intent intact. The AI also generates the title, picks the most relevant focus indicator from the engagement catalog, and suggests scope (actionType) and due date. The result can be sent directly to POST /v1/company/actions with source=AI once the user confirms. Note: this call invokes an external LLM and may take a few seconds.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

commentIdstringRequired

Comment (idea) identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Responses

200

Action suggestion generated from the comment

*/*

AI-generated action suggestion — all fields pre-filled and ready for user review. Can be forwarded directly to POST /v1/company/actions after confirmation.

titlestringOptional

Short title describing the suggested action

Example: Implementar rituales de reconocimiento semanales

descriptionstringOptional

Detailed execution plan: how, when, and why this action addresses the focus indicator

Example: Cada viernes dedicar 10 minutos al inicio del standup a reconocer un logro concreto de un miembro del equipo.

actionTypestring · enumOptional

Recommended action scope. MANAGER for individual-team actions; COMPANY for cross-team initiatives.

Example: MANAGERPossible values:

dueDatestring · date-timeOptional

Suggested target completion date. Map this directly to the dueDate field when creating the action.

Example: 2025-09-01T00:00:00.000Z

hierarchyIdsstring[]Optional

Areas/hierarchies this action is pre-scoped to. Pre-populated from the teamId in the suggestion request; empty for company-wide suggestions.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

assigneesstring[]Optional

Responsible managers. Empty — must be filled by the user before confirming.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

currentValuenumber · doubleOptional

Current measured value of the focus indicator at the time the suggestion was generated. Provides context to show the user the baseline the action targets (e.g. 4.3 for a score on a 0–10 scale, or 62 for HI on a 0–100 scale). Null when the measurement was unavailable for the requested period.

rationalestringOptional

Brief explanation of why the model recommends this action, based on the data analysed.

Example: El factor Reconocimiento lleva 3 pulsos consecutivos con valores inferiores a 5, lo que suele correlacionar con mayor rotación.

sourcestring · enumOptional

Always AI for suggestions generated by this endpoint.

Example: AIPossible values:

404

Comment not found in this company, or comment has no text

*/*

500

AI service unavailable or returned an unparseable response

*/*

post/api/v1/company/actions/suggest/from-comment/{commentId}

POST /api/v1/company/actions/suggest/from-comment/{commentId} HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Accept: */*

{
  "title": "Implementar rituales de reconocimiento semanales",
  "description": "Cada viernes dedicar 10 minutos al inicio del standup a reconocer un logro concreto de un miembro del equipo.",
  "focusItems": [
    {
      "focusType": "SCORE",
      "focusId": "text",
      "targetValue": 1,
      "targetTimestamp": "2026-01-01T00:00:00.000Z"
    }
  ],
  "actionType": "MANAGER",
  "dueDate": "2025-09-01T00:00:00.000Z",
  "hierarchyIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "assignees": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "currentValue": 1,
  "rationale": "El factor Reconocimiento lleva 3 pulsos consecutivos con valores inferiores a 5, lo que suele correlacionar con mayor rotación.",
  "source": "AI"
}

Export all company actions & plans to Excel

post

Triggers an asynchronous Excel export of ALL action plans (with their actions) for the company in a single workbook. 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.

Authorizations

SessionIdstringRequired

SessionId

Responses

200

Export triggered — file will be sent by e-mail

No content

post/api/v1/company/actions/excel

POST /api/v1/company/actions/excel HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Accept: */*

200

Export triggered — file will be sent by e-mail

No content

Generate AI actions for an existing plan (IA #2)

post

Returns a DRAFT set of actions that fit an existing plan, given the plan's context. Pass the plan's planTitle/planDescription in the body so the AI tailors the actions to the plan's goal; when omitted, the plan id is used as minimal fallback context.

Count: count controls how many actions are generated (clamped to 1–5; defaults to 3).

Not persisted: the results are drafts. The client forwards each one to the create-action endpoint after the user confirms. Note: this call invokes an external LLM and may take a few seconds.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

planIdstringRequired

Plan identifier the generated actions belong to

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Body

Optional parameters for generating actions that fit an existing plan

planTitlestringOptional

Title of the plan the actions must fit into. Improves the relevance of the generated actions. Optional — when omitted the plan id is used as fallback context.

Example: Plan de mejora del reconocimiento

planDescriptionstringOptional

Goal/description of the plan the actions must serve. Optional.

Example: Reforzar el reconocimiento entre equipos.

countinteger · int32 · min: 1 · max: 5Optional

How many actions to generate. Clamped to the range 1–5; defaults to 3 when omitted.

Default: 3Example: 3

teamIdstringOptional

Restrict score analysis to a specific team/hierarchy. When omitted, company-wide data is used.

Example: 507f1f77bcf86cd799439012

fromstring · date-timeOptional

Start of the measurement window (inclusive). When omitted, defaults to 30 days before 'to' (or before now if 'to' is also omitted).

Example: 2025-03-01T00:00:00.000Z

tostring · date-timeOptional

End of the measurement window (inclusive). Defaults to the current date/time when omitted.

Example: 2025-05-31T23:59:59.000Z

hintstringOptional

Free-text hint that gives the AI additional context about the current situation. Max 500 characters.

Example: Our team had two people leave last month and morale seems low.

languagestringOptional

BCP-47 language code for the suggestion text. Defaults to 'es' when omitted.

Default: esExample: es

Responses

200

Action drafts generated (may be an empty list when no engagement data is available)

*/*

AI-generated action suggestion — all fields pre-filled and ready for user review. Can be forwarded directly to POST /v1/company/actions after confirmation.

titlestringOptional

Short title describing the suggested action

Example: Implementar rituales de reconocimiento semanales

descriptionstringOptional

Detailed execution plan: how, when, and why this action addresses the focus indicator

Example: Cada viernes dedicar 10 minutos al inicio del standup a reconocer un logro concreto de un miembro del equipo.

actionTypestring · enumOptional

Recommended action scope. MANAGER for individual-team actions; COMPANY for cross-team initiatives.

Example: MANAGERPossible values:

dueDatestring · date-timeOptional

Suggested target completion date. Map this directly to the dueDate field when creating the action.

Example: 2025-09-01T00:00:00.000Z

hierarchyIdsstring[]Optional

Areas/hierarchies this action is pre-scoped to. Pre-populated from the teamId in the suggestion request; empty for company-wide suggestions.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

assigneesstring[]Optional

Responsible managers. Empty — must be filled by the user before confirming.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

currentValuenumber · doubleOptional

Current measured value of the focus indicator at the time the suggestion was generated. Provides context to show the user the baseline the action targets (e.g. 4.3 for a score on a 0–10 scale, or 62 for HI on a 0–100 scale). Null when the measurement was unavailable for the requested period.

rationalestringOptional

Brief explanation of why the model recommends this action, based on the data analysed.

Example: El factor Reconocimiento lleva 3 pulsos consecutivos con valores inferiores a 5, lo que suele correlacionar con mayor rotación.

sourcestring · enumOptional

Always AI for suggestions generated by this endpoint.

Example: AIPossible values:

400

Request validation failed

*/*

500

AI service unavailable or returned an unparseable response

*/*

post/api/v1/company/actions/ai/{planId}/generate-actions

POST /api/v1/company/actions/ai/{planId}/generate-actions HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 311

{
  "planTitle": "Plan de mejora del reconocimiento",
  "planDescription": "Reforzar el reconocimiento entre equipos.",
  "count": 3,
  "teamId": "507f1f77bcf86cd799439012",
  "from": "2025-03-01T00:00:00.000Z",
  "to": "2025-05-31T23:59:59.000Z",
  "hint": "Our team had two people leave last month and morale seems low.",
  "language": "es"
}

[
  {
    "title": "Implementar rituales de reconocimiento semanales",
    "description": "Cada viernes dedicar 10 minutos al inicio del standup a reconocer un logro concreto de un miembro del equipo.",
    "focusItems": [
      {
        "focusType": "SCORE",
        "focusId": "text",
        "targetValue": 1,
        "targetTimestamp": "2026-01-01T00:00:00.000Z"
      }
    ],
    "actionType": "MANAGER",
    "dueDate": "2025-09-01T00:00:00.000Z",
    "hierarchyIds": [
      "64f8a0e2d5b7c9a1e3f4a5b6"
    ],
    "assignees": [
      "64f8a0e2d5b7c9a1e3f4a5b6"
    ],
    "currentValue": 1,
    "rationale": "El factor Reconocimiento lleva 3 pulsos consecutivos con valores inferiores a 5, lo que suele correlacionar con mayor rotación.",
    "source": "AI"
  }
]

Recommend Happyforce platform actions (IA #4)

post

Analyses the company's engagement data and recommends concrete ways to use Happyforce features (check-in, announcement, conversation, survey, recognition) to act on the current situation, pre-filling ready-to-use content for each.

Recommendation only: these recommendations are NOT executed automatically — the user acts on them through the corresponding feature.

Date window: controlled by from/to in the request body — defaults to the last 30 days when omitted.

Team scope: when teamId is provided, metric queries are filtered to that team's hierarchy. Note: this call invokes an external LLM and may take a few seconds.

Authorizations

SessionIdstringRequired

SessionId

Body

Optional parameters that narrow the AI action suggestion context

teamIdstringOptional

Restrict score analysis to a specific team/hierarchy. When omitted, company-wide data is used.

Example: 507f1f77bcf86cd799439012

fromstring · date-timeOptional

Start of the measurement window (inclusive). When omitted, defaults to 30 days before 'to' (or before now if 'to' is also omitted).

Example: 2025-03-01T00:00:00.000Z

tostring · date-timeOptional

End of the measurement window (inclusive). Defaults to the current date/time when omitted.

Example: 2025-05-31T23:59:59.000Z

hintstringOptional

Free-text hint that gives the AI additional context about the current situation. Max 500 characters.

Example: Our team had two people leave last month and morale seems low.

languagestringOptional

BCP-47 language code for the suggestion text. Defaults to 'es' when omitted.

Default: esExample: es

Responses

200

Recommendations generated (may be an empty list when no engagement data is available)

*/*

AI recommendation to use a Happyforce feature, with all actionable fields pre-filled. Recommendation only — never executed automatically; the user acts on it through the corresponding feature.

platformFeaturestring · enumOptional

Happyforce feature to use.

Example: CHECKINPossible values:

titlestringOptional

Short imperative title of the recommendation.

Example: Lanzar un check-in sobre carga de trabajo

suggestedContentstringOptional

Ready-to-use draft content for the feature (e.g. the check-in question text or the announcement body). Publishable with minimal edits.

Example: ¿Cómo valoras tu carga de trabajo esta semana?

actionTypestring · enumOptional

Recommended action scope. MANAGER for individual-team actions; COMPANY for cross-team initiatives.

Example: MANAGERPossible values:

dueDatestring · date-timeOptional

Suggested target completion date for the follow-up action.

Example: 2025-09-01T00:00:00.000Z

hierarchyIdsstring[]Optional

Areas/hierarchies this recommendation is pre-scoped to. Pre-populated from the teamId in the request; empty for company-wide recommendations.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

assigneesstring[]Optional

Responsible managers. Pre-populated from the requested team scope when available; otherwise empty and filled by the user before confirming.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

currentValuenumber · doubleOptional

Current measured value of the focus indicator at the time the recommendation was generated. Provides the baseline the recommendation targets. Null when the measurement was unavailable.

rationalestringOptional

Why this feature and this content fit the current situation, citing the relevant signal.

Example: El factor Carga de trabajo ha bajado 1,2 puntos en el último pulso.

400

Request validation failed

*/*

500

AI service unavailable or returned an unparseable response

*/*

post/api/v1/company/actions/ai/platform

POST /api/v1/company/actions/ai/platform HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 191

{
  "teamId": "507f1f77bcf86cd799439012",
  "from": "2025-03-01T00:00:00.000Z",
  "to": "2025-05-31T23:59:59.000Z",
  "hint": "Our team had two people leave last month and morale seems low.",
  "language": "es"
}

[
  {
    "platformFeature": "CHECKIN",
    "title": "Lanzar un check-in sobre carga de trabajo",
    "suggestedContent": "¿Cómo valoras tu carga de trabajo esta semana?",
    "focusItems": [
      {
        "focusType": "SCORE",
        "focusId": "text",
        "targetValue": 1,
        "targetTimestamp": "2026-01-01T00:00:00.000Z"
      }
    ],
    "actionType": "MANAGER",
    "dueDate": "2025-09-01T00:00:00.000Z",
    "hierarchyIds": [
      "64f8a0e2d5b7c9a1e3f4a5b6"
    ],
    "assignees": [
      "64f8a0e2d5b7c9a1e3f4a5b6"
    ],
    "currentValue": 1,
    "rationale": "El factor Carga de trabajo ha bajado 1,2 puntos en el último pulso."
  }
]

Generate an AI action plan (IA #1)

post

Analyses the company's engagement data for the requested period and returns a DRAFT improvement plan (title, goal) together with an initial set of 2–5 actions targeting the weakest or most-declining indicators.

Date window: controlled by from/to in the request body — defaults to the last 30 days when omitted.

Team scope: when teamId is provided, metric queries are filtered to that team's hierarchy.

Not persisted: the result is a draft. The client creates the plan and its actions through the standard endpoints after the user reviews and optionally adjusts any field. Note: this call invokes an external LLM and may take a few seconds.

Authorizations

SessionIdstringRequired

SessionId

Body

Optional parameters that narrow the AI action suggestion context

teamIdstringOptional

Restrict score analysis to a specific team/hierarchy. When omitted, company-wide data is used.

Example: 507f1f77bcf86cd799439012

fromstring · date-timeOptional

Start of the measurement window (inclusive). When omitted, defaults to 30 days before 'to' (or before now if 'to' is also omitted).

Example: 2025-03-01T00:00:00.000Z

tostring · date-timeOptional

End of the measurement window (inclusive). Defaults to the current date/time when omitted.

Example: 2025-05-31T23:59:59.000Z

hintstringOptional

Free-text hint that gives the AI additional context about the current situation. Max 500 characters.

Example: Our team had two people leave last month and morale seems low.

languagestringOptional

BCP-47 language code for the suggestion text. Defaults to 'es' when omitted.

Default: esExample: es

Responses

200

Plan draft generated (its actions list may be empty when no engagement data is available)

*/*

AI-generated action plan draft with its initial actions. Not persisted — the user reviews it before creating the plan and actions through the standard endpoints.

titlestringOptional

Short, goal-oriented plan title.

Example: Plan de mejora del reconocimiento

descriptionstringOptional

Plan goal: what the plan aims to improve and why, grounded in the analysed data.

Example: Reforzar el reconocimiento entre equipos, cuyo factor lleva tres pulsos por debajo de 5.

sourcestring · enumOptional

Always AI for plans generated by this endpoint.

Example: AIPossible values:

400

Request validation failed

*/*

500

AI service unavailable or returned an unparseable response

*/*

post/api/v1/company/actions/ai/generate-plan

POST /api/v1/company/actions/ai/generate-plan HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 191

{
  "teamId": "507f1f77bcf86cd799439012",
  "from": "2025-03-01T00:00:00.000Z",
  "to": "2025-05-31T23:59:59.000Z",
  "hint": "Our team had two people leave last month and morale seems low.",
  "language": "es"
}

{
  "title": "Plan de mejora del reconocimiento",
  "description": "Reforzar el reconocimiento entre equipos, cuyo factor lleva tres pulsos por debajo de 5.",
  "actions": [
    {
      "title": "Implementar rituales de reconocimiento semanales",
      "description": "Cada viernes dedicar 10 minutos al inicio del standup a reconocer un logro concreto de un miembro del equipo.",
      "focusItems": [
        {
          "focusType": "SCORE",
          "focusId": "text",
          "targetValue": 1,
          "targetTimestamp": "2026-01-01T00:00:00.000Z"
        }
      ],
      "actionType": "MANAGER",
      "dueDate": "2025-09-01T00:00:00.000Z",
      "hierarchyIds": [
        "64f8a0e2d5b7c9a1e3f4a5b6"
      ],
      "assignees": [
        "64f8a0e2d5b7c9a1e3f4a5b6"
      ],
      "currentValue": 1,
      "rationale": "El factor Reconocimiento lleva 3 pulsos consecutivos con valores inferiores a 5, lo que suele correlacionar con mayor rotación.",
      "source": "AI"
    }
  ],
  "source": "AI"
}

Generate an AI plan from negative engagement insights (IA #3)

post

Turns free-text negative engagement insights (critical comments, declining indicators, detractor feedback) into a DRAFT improvement plan with an initial set of actions that address the underlying problem.

Required: the insights field (max 4000 characters).

Not persisted: the result is a draft. The client creates the plan and its actions through the standard endpoints after the user reviews and optionally adjusts any field. Note: this call invokes an external LLM and may take a few seconds.

Authorizations

SessionIdstringRequired

SessionId

Body

Parameters for generating an improvement plan from negative engagement insights

insightsstring · max: 4000Required

Free-text negative engagement insights the plan must address (critical comments, declining indicators, detractor feedback). Required. Max 4000 characters.

Example: Varios comentarios mencionan falta de comunicación del liderazgo y el eNPS ha caído 15 puntos.

teamIdstringOptional

Restrict score analysis to a specific team/hierarchy. When omitted, company-wide data is used.

Example: 507f1f77bcf86cd799439012

fromstring · date-timeOptional

Start of the measurement window (inclusive). When omitted, defaults to 30 days before 'to' (or before now if 'to' is also omitted).

Example: 2025-03-01T00:00:00.000Z

tostring · date-timeOptional

End of the measurement window (inclusive). Defaults to the current date/time when omitted.

Example: 2025-05-31T23:59:59.000Z

hintstringOptional

Free-text hint that gives the AI additional context about the current situation. Max 500 characters.

Example: Our team had two people leave last month and morale seems low.

languagestringOptional

BCP-47 language code for the suggestion text. Defaults to 'es' when omitted.

Default: esExample: es

Responses

200

Plan draft generated (its actions list may be empty when no engagement data is available)

*/*

AI-generated action plan draft with its initial actions. Not persisted — the user reviews it before creating the plan and actions through the standard endpoints.

titlestringOptional

Short, goal-oriented plan title.

Example: Plan de mejora del reconocimiento

descriptionstringOptional

Plan goal: what the plan aims to improve and why, grounded in the analysed data.

Example: Reforzar el reconocimiento entre equipos, cuyo factor lleva tres pulsos por debajo de 5.

sourcestring · enumOptional

Always AI for plans generated by this endpoint.

Example: AIPossible values:

400

Request validation failed (e.g. blank insights)

*/*

500

AI service unavailable or returned an unparseable response

*/*

post/api/v1/company/actions/ai/from-engagement

POST /api/v1/company/actions/ai/from-engagement HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 301

{
  "insights": "Varios comentarios mencionan falta de comunicación del liderazgo y el eNPS ha caído 15 puntos.",
  "teamId": "507f1f77bcf86cd799439012",
  "from": "2025-03-01T00:00:00.000Z",
  "to": "2025-05-31T23:59:59.000Z",
  "hint": "Our team had two people leave last month and morale seems low.",
  "language": "es"
}

{
  "title": "Plan de mejora del reconocimiento",
  "description": "Reforzar el reconocimiento entre equipos, cuyo factor lleva tres pulsos por debajo de 5.",
  "actions": [
    {
      "title": "Implementar rituales de reconocimiento semanales",
      "description": "Cada viernes dedicar 10 minutos al inicio del standup a reconocer un logro concreto de un miembro del equipo.",
      "focusItems": [
        {
          "focusType": "SCORE",
          "focusId": "text",
          "targetValue": 1,
          "targetTimestamp": "2026-01-01T00:00:00.000Z"
        }
      ],
      "actionType": "MANAGER",
      "dueDate": "2025-09-01T00:00:00.000Z",
      "hierarchyIds": [
        "64f8a0e2d5b7c9a1e3f4a5b6"
      ],
      "assignees": [
        "64f8a0e2d5b7c9a1e3f4a5b6"
      ],
      "currentValue": 1,
      "rationale": "El factor Reconocimiento lleva 3 pulsos consecutivos con valores inferiores a 5, lo que suele correlacionar con mayor rotación.",
      "source": "AI"
    }
  ],
  "source": "AI"
}

Generate an AI plan and actions from a comment/idea (IA #5)

post

Takes an employee comment/idea (identified by commentId) as the seed and returns a DRAFT improvement plan whose goal addresses that idea, together with an initial set of actions that develop it. Replaces the single-action /suggest/from-comment/{commentId} flow: since every action now belongs to a plan, this returns a full plan draft instead of a standalone action.

Optional body: hint (free text, extra context to refine the suggestion) and language.

Not persisted: the result is a draft. The client creates the plan and its actions through the standard endpoints after the user reviews and optionally adjusts any field. Note: this call invokes an external LLM and may take a few seconds.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

commentIdstringRequired

Identifier of the source comment/idea

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Body

Optional parameters for generating a plan and actions from a comment/idea

hintstring · max: 500Optional

Free-text hint that gives the AI additional context to refine the suggestion. Max 500 characters.

Example: Encaja con la iniciativa de flexibilidad horaria que estamos evaluando.

languagestringOptional

BCP-47 language code for the suggestion text. Defaults to 'es' when omitted.

Default: esExample: es

Responses

200

Plan draft generated from the comment (its actions list may be empty when no engagement data is available)

*/*

AI-generated action plan draft with its initial actions. Not persisted — the user reviews it before creating the plan and actions through the standard endpoints.

titlestringOptional

Short, goal-oriented plan title.

Example: Plan de mejora del reconocimiento

descriptionstringOptional

Plan goal: what the plan aims to improve and why, grounded in the analysed data.

Example: Reforzar el reconocimiento entre equipos, cuyo factor lleva tres pulsos por debajo de 5.

sourcestring · enumOptional

Always AI for plans generated by this endpoint.

Example: AIPossible values:

404

Comment not found in this company or has no text content

*/*

500

AI service unavailable or returned an unparseable response

*/*

post/api/v1/company/actions/ai/from-comment/{commentId}

POST /api/v1/company/actions/ai/from-comment/{commentId} HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 98

{
  "hint": "Encaja con la iniciativa de flexibilidad horaria que estamos evaluando.",
  "language": "es"
}

{
  "title": "Plan de mejora del reconocimiento",
  "description": "Reforzar el reconocimiento entre equipos, cuyo factor lleva tres pulsos por debajo de 5.",
  "actions": [
    {
      "title": "Implementar rituales de reconocimiento semanales",
      "description": "Cada viernes dedicar 10 minutos al inicio del standup a reconocer un logro concreto de un miembro del equipo.",
      "focusItems": [
        {
          "focusType": "SCORE",
          "focusId": "text",
          "targetValue": 1,
          "targetTimestamp": "2026-01-01T00:00:00.000Z"
        }
      ],
      "actionType": "MANAGER",
      "dueDate": "2025-09-01T00:00:00.000Z",
      "hierarchyIds": [
        "64f8a0e2d5b7c9a1e3f4a5b6"
      ],
      "assignees": [
        "64f8a0e2d5b7c9a1e3f4a5b6"
      ],
      "currentValue": 1,
      "rationale": "El factor Reconocimiento lleva 3 pulsos consecutivos con valores inferiores a 5, lo que suele correlacionar con mayor rotación.",
      "source": "AI"
    }
  ],
  "source": "AI"
}

Get action details

get

Returns the full action aggregate. Overdue in-progress actions are expired on-the-fly before the response.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

actionIdstringRequired

Action identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Responses

200

Action found

*/*

Complete action payload returned by the API

idstringOptional

Unique action identifier

Example: 507f1f77bcf86cd799439011

companyIdstringOptional

Company that owns this action

Example: 507f1f77bcf86cd799439010

planIdstringOptional

Parent action plan identifier. Every action belongs to a plan.

Example: 507f1f77bcf86cd799439013

hierarchyIdsstring[]Optional

Areas/hierarchies this action targets. Empty means company-wide scope.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

groupIdsstring[]Optional

Groups this action targets.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

actionTypestring · enumOptional

Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.

Example: MANAGERPossible values:

sourcestring · enumOptional

How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.

Example: MANUALPossible values:

visibilitystring · enumOptional

Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.

Example: PRIVATEPossible values:

statusstring · enumOptional

Aggregate lifecycle status (computed from all assignee states).

Example: IN_PROGRESSPossible values:

completionPercentinteger · int32Optional

Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored.

Example: 50

dueDatestring · date-timeOptional

Target completion date

Example: 2025-06-30T23:59:59.000Z

startedAtstring · date-timeOptional

Timestamp when the first assignee moved to IN_PROGRESS

completedAtstring · date-timeOptional

Timestamp when all assignees reached a terminal status

createdBystringOptional

User who created this action

Example: 507f1f77bcf86cd799439012

createdAtstring · date-timeOptional

Creation timestamp

updatedAtstring · date-timeOptional

Last modification timestamp

404

Action not found in this company

*/*

get/api/v1/company/actions/{actionId}

GET /api/v1/company/actions/{actionId} HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Accept: */*

{
  "id": "507f1f77bcf86cd799439011",
  "companyId": "507f1f77bcf86cd799439010",
  "planId": "507f1f77bcf86cd799439013",
  "plan": {
    "id": "507f1f77bcf86cd799439013",
    "title": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    },
    "description": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    }
  },
  "title": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "description": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "focusItems": [
    {
      "focusType": "SCORE",
      "focusId": "text",
      "targetValue": 1,
      "targetTimestamp": "2026-01-01T00:00:00.000Z"
    }
  ],
  "assigneeStatuses": [
    {
      "assigneeId": "507f1f77bcf86cd799439011",
      "status": "IN_PROGRESS",
      "startedAt": "2026-01-01T00:00:00.000Z",
      "completedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "hierarchyIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "groupIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "characteristics": [
    {
      "characteristicId": "64f8a0e2d5b7c9a1e3f4a5b6",
      "id": "64f8a0e2d5b7c9a1e3f4a5b6",
      "questionType": "DATE",
      "value": true
    }
  ],
  "actionType": "MANAGER",
  "source": "MANUAL",
  "visibility": "PRIVATE",
  "status": "IN_PROGRESS",
  "completionPercent": 50,
  "dueDate": "2025-06-30T23:59:59.000Z",
  "startedAt": "2026-01-01T00:00:00.000Z",
  "completedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "507f1f77bcf86cd799439012",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "notes": [
    {
      "id": "507f1f77bcf86cd799439020",
      "authorId": "507f1f77bcf86cd799439015",
      "content": "Feedback de la retro mejoró tras introducir los reconocimientos entre pares.",
      "visibility": "SHARED",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Delete an action

delete

Permanently removes an action. Only the action creator or an admin can delete; legacy actions 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.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

actionIdstringRequired

Action identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Responses

204

Action deleted

No content

403

Caller is not the creator or an admin

404

Action not found in this company

delete/api/v1/company/actions/{actionId}

DELETE /api/v1/company/actions/{actionId} HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Accept: */*

No content

Patch mutable action fields

patch

Applies a partial update to an action. Only non-null fields are updated. Cannot be applied to actions in a terminal status (COMPLETED, PARTIALLY_COMPLETED, FAILED, EXPIRED). Immutable fields (focusItems, actionType) are ignored even if provided.

Authorizations

SessionIdstringRequired

SessionId

Path parameters

actionIdstringRequired

Action identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Body

Partial update payload for an existing action. Only non-null fields are applied.

dueDatestring · date-timeOptional

Extended due date. Must not be earlier than the action creation date.

Example: 2025-09-30T23:59:59.000Z

sourcestring · enumOptional

Updated action origin.

Example: SUGGESTIONPossible values:

assigneesstring[]Optional

Replaces the full assignees list when non-null. Use this to add or remove co-responsible managers. Must be non-empty if provided.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

planIdstringOptional

Moves the action to the specified plan when non-null. The plan must belong to the same company. Omit (or send null) to leave the current plan unchanged.

Example: 507f1f77bcf86cd799439013

visibilitystring · enumOptional

New visibility. Null means no change.

Possible values:

Responses

200

Action updated successfully

*/*

Complete action payload returned by the API

idstringOptional

Unique action identifier

Example: 507f1f77bcf86cd799439011

companyIdstringOptional

Company that owns this action

Example: 507f1f77bcf86cd799439010

planIdstringOptional

Parent action plan identifier. Every action belongs to a plan.

Example: 507f1f77bcf86cd799439013

hierarchyIdsstring[]Optional

Areas/hierarchies this action targets. Empty means company-wide scope.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

groupIdsstring[]Optional

Groups this action targets.

Example: 64f8a0e2d5b7c9a1e3f4a5b6

actionTypestring · enumOptional

Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.

Example: MANAGERPossible values:

sourcestring · enumOptional

How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.

Example: MANUALPossible values:

visibilitystring · enumOptional

Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.

Example: PRIVATEPossible values:

statusstring · enumOptional

Aggregate lifecycle status (computed from all assignee states).

Example: IN_PROGRESSPossible values:

completionPercentinteger · int32Optional

Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored.

Example: 50

dueDatestring · date-timeOptional

Target completion date

Example: 2025-06-30T23:59:59.000Z

startedAtstring · date-timeOptional

Timestamp when the first assignee moved to IN_PROGRESS

completedAtstring · date-timeOptional

Timestamp when all assignees reached a terminal status

createdBystringOptional

User who created this action

Example: 507f1f77bcf86cd799439012

createdAtstring · date-timeOptional

Creation timestamp

updatedAtstring · date-timeOptional

Last modification timestamp

400

Invalid field values, dueDate before creation date, or action is already closed

*/*

404

Action not found in this company

*/*

patch/api/v1/company/actions/{actionId}

PATCH /api/v1/company/actions/{actionId} HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 373

{
  "title": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "description": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "dueDate": "2025-09-30T23:59:59.000Z",
  "source": "SUGGESTION",
  "assignees": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "planId": "507f1f77bcf86cd799439013",
  "visibility": "PUBLIC"
}

{
  "id": "507f1f77bcf86cd799439011",
  "companyId": "507f1f77bcf86cd799439010",
  "planId": "507f1f77bcf86cd799439013",
  "plan": {
    "id": "507f1f77bcf86cd799439013",
    "title": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    },
    "description": {
      "defaultValue": "Happy birthday!",
      "langValues": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "valid": true
    }
  },
  "title": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "description": {
    "defaultValue": "Happy birthday!",
    "langValues": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "valid": true
  },
  "focusItems": [
    {
      "focusType": "SCORE",
      "focusId": "text",
      "targetValue": 1,
      "targetTimestamp": "2026-01-01T00:00:00.000Z"
    }
  ],
  "assigneeStatuses": [
    {
      "assigneeId": "507f1f77bcf86cd799439011",
      "status": "IN_PROGRESS",
      "startedAt": "2026-01-01T00:00:00.000Z",
      "completedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "hierarchyIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "groupIds": [
    "64f8a0e2d5b7c9a1e3f4a5b6"
  ],
  "characteristics": [
    {
      "characteristicId": "64f8a0e2d5b7c9a1e3f4a5b6",
      "id": "64f8a0e2d5b7c9a1e3f4a5b6",
      "questionType": "DATE",
      "value": true
    }
  ],
  "actionType": "MANAGER",
  "source": "MANUAL",
  "visibility": "PRIVATE",
  "status": "IN_PROGRESS",
  "completionPercent": 50,
  "dueDate": "2025-06-30T23:59:59.000Z",
  "startedAt": "2026-01-01T00:00:00.000Z",
  "completedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "507f1f77bcf86cd799439012",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "notes": [
    {
      "id": "507f1f77bcf86cd799439020",
      "authorId": "507f1f77bcf86cd799439015",
      "content": "Feedback de la retro mejoró tras introducir los reconocimientos entre pares.",
      "visibility": "SHARED",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Get impact measurement

get

Returns the impact document for a closed action, containing metric readings at three points in time: baseline (creation), at-closure, and the most recent periodic re-evaluation.

Scope: managers receive their own area-scoped snapshot; admins receive the global company-wide snapshot. Admins can also request a specific manager's scoped snapshot via the optional assigneeId parameter.

Returns 404 when the action has never been closed or the impact capture has not completed yet (it runs asynchronously after closure).

Authorizations

SessionIdstringRequired

SessionId

Path parameters

actionIdstringRequired

Action identifier

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Query parameters

assigneeIdstringOptional

Admin only: request a specific manager's scoped impact snapshot instead of the global one

Example: 64f8a0e2d5b7c9a1e3f4a5b6

Responses

200

Impact document found and returned

*/*

Impact measurement for a closed action, showing how the focus indicators evolved before, at and after the action was executed

idstringOptional

Impact document identifier

Example: 507f1f77bcf86cd799439011

actionIdstringOptional

Related action identifier

Example: 507f1f77bcf86cd799439012

assigneeIdstringOptional

Manager this snapshot is scoped to. Null for the global company-wide snapshot.

Example: 507f1f77bcf86cd799439013

closureStatusstring · enumOptional

Terminal state that triggered impact capture

Example: COMPLETEDPossible values:

closedAtstring · date-timeOptional

When the action reached its terminal state

windowEndsAtstring · date-timeOptional

When the measurement window closes — no more re-evaluations after this date (closedAt + windowDays)

evaluationCountinteger · int32Optional

Number of periodic re-evaluations performed so far

Example: 3

lastEvaluatedAtstring · date-timeOptional

Timestamp of the most recent periodic re-evaluation

impactSummarystringOptional

AI-generated, plain-language summary of the impact, scoped to what this caller sees. Null until the summary has been generated (see summaryStatus).

summaryStatusstring · enumOptional

Generation status of the AI summary. When PENDING or RUNNING the client should re-request this endpoint to poll until COMPOSED.

Example: COMPOSEDPossible values:

summaryLanguagestringOptional

Language the AI summary is (or will be) written in

Example: es

404

No impact document for this action

*/*

get/api/v1/company/actions/{actionId}/impact

GET /api/v1/company/actions/{actionId}/impact HTTP/1.1
Host: api.happyforce.com
SessionId: YOUR_API_KEY
Accept: */*

{
  "id": "507f1f77bcf86cd799439011",
  "actionId": "507f1f77bcf86cd799439012",
  "assigneeId": "507f1f77bcf86cd799439013",
  "closureStatus": "COMPLETED",
  "closedAt": "2026-01-01T00:00:00.000Z",
  "baseline": [
    {
      "focusType": "FACTOR",
      "focusId": "recognition",
      "value": 6.4,
      "delta": 0.8,
      "participantCount": 34,
      "measuredAt": "2026-01-01T00:00:00.000Z",
      "reliability": "MODERATE",
      "normalizedDelta": 8,
      "netDelta": 0.5,
      "normalizedNetDelta": 5
    }
  ],
  "atClosure": [
    {
      "focusType": "FACTOR",
      "focusId": "recognition",
      "value": 6.4,
      "delta": 0.8,
      "participantCount": 34,
      "measuredAt": "2026-01-01T00:00:00.000Z",
      "reliability": "MODERATE",
      "normalizedDelta": 8,
      "netDelta": 0.5,
      "normalizedNetDelta": 5
    }
  ],
  "latest": [
    {
      "focusType": "FACTOR",
      "focusId": "recognition",
      "value": 6.4,
      "delta": 0.8,
      "participantCount": 34,
      "measuredAt": "2026-01-01T00:00:00.000Z",
      "reliability": "MODERATE",
      "normalizedDelta": 8,
      "netDelta": 0.5,
      "normalizedNetDelta": 5
    }
  ],
  "windowEndsAt": "2026-01-01T00:00:00.000Z",
  "evaluationCount": 3,
  "lastEvaluatedAt": "2026-01-01T00:00:00.000Z",
  "impactSummary": "text",
  "summaryStatus": "COMPOSED",
  "summaryLanguage": "es"
}