openapi: 3.0.3
info:
  title: Engagedly Activities Users API
  description: 'REST API for the Engagedly people strategy execution platform. Provides endpoints for managing users, departments, locations, job titles, business units, permissions, user attributes, and employee activities such as praises and recognition. Supports performance review workflows, goal management, and organizational data integration using header-based authentication with ClientKey and SecretKey.

    '
  version: beta
  contact:
    url: https://engagedly.com
  license:
    name: Proprietary
servers:
- url: https://api.engagedly.com/beta
  description: Production API server
security:
- clientKeyAuth: []
  secretKeyAuth: []
tags:
- name: Users
  description: Manage user profiles, permissions, and activation status
paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      description: Returns a paginated list of all users in the organization.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/sizeParam'
      - name: include
        in: query
        description: Comma-separated list of related data to include
        schema:
          type: string
          example: primary_reporter,direct_reports
      - name: email
        in: query
        description: Filter users by email address
        schema:
          type: string
          format: email
      responses:
        '200':
          description: Paginated list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUser
      summary: Create a new user
      description: 'Creates a new user in the organization. Both system attributes and custom attributes (using their attribute_key as field names) can be included in the request body.

        '
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequest'
            example:
              first_name: John
              last_name: Doe
              email: john.doe@company.com
              employee_id: EMP001
              departments:
              - dept-123
              businesses:
              - biz-456
              hr_managers:
              - manager-789
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSingleResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /users/block-reason-codes:
    get:
      operationId: listBlockReasonCodes
      summary: Get block reason codes
      description: Returns all available reason codes for deactivating (blocking) a user.
      tags:
      - Users
      responses:
        '200':
          description: List of block reason codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockReasonCodeListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{id}:
    get:
      operationId: getUser
      summary: Get a single user
      description: Returns detailed information for a single user by ID.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      - name: include
        in: query
        description: Comma-separated list of related data to include
        schema:
          type: string
          example: primary_reporter,direct_reports,hr_managers,secondary_managers
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSingleResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateUser
      summary: Update an existing user
      description: Fully updates an existing user record by ID.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSingleResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    patch:
      operationId: partialUpdateUser
      summary: Partially update an existing user
      description: 'Partially updates a user record. Only the fields provided in the request body are updated.

        '
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: User partially updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSingleResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /users/{id}/profile/picture:
    put:
      operationId: updateUserProfilePicture
      summary: Update user's profile picture
      description: Uploads and sets a new profile picture for the specified user.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                profile_picture:
                  type: string
                  format: byte
                  description: Base64-encoded bytes of the picture
      responses:
        '200':
          description: Profile picture updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{id}/deactivate:
    put:
      operationId: deactivateUser
      summary: Deactivate a user
      description: Deactivates (blocks) the specified user, optionally with a reason code.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                block_reason_code:
                  type: string
                  description: Optional code indicating the reason for deactivation
                  example: involuntary
      responses:
        '200':
          description: User deactivated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSingleResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{id}/activate:
    put:
      operationId: activateUser
      summary: Activate a user
      description: Re-activates a previously deactivated user.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      responses:
        '200':
          description: User activated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSingleResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{id}/permissions:
    get:
      operationId: getUserPermissions
      summary: Get permissions of a user
      description: Returns all permission roles assigned to the specified user.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      responses:
        '200':
          description: User permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPermissionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateUserPermissions
      summary: Update permissions of a user
      description: Replaces the permission roles assigned to the specified user.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/idPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                permission_ids:
                  type: array
                  items:
                    type: integer
                  description: Array of permission IDs to assign
      responses:
        '200':
          description: User permissions updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPermissionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    UnprocessableEntity:
      description: Unprocessable Entity — validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not Found — resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — invalid or missing ClientKey/SecretKey
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    BlockReasonCodeListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlockReasonCode'
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
          example: name
        message:
          type: string
          example: Mandatory attribute missing
        code:
          type: string
          example: missing_field
    User:
      type: object
      properties:
        id:
          type: string
          example: b62167d0-2718-4e45-9721-27535991becf
        name:
          type: string
          example: Adam Smith
        status:
          type: string
          enum:
          - Active
          - Blocked
          example: Active
        email:
          type: string
          format: email
          example: adam.smith@company.com
        first_name:
          type: string
          example: Adam
        middle_name:
          type: string
          nullable: true
        last_name:
          type: string
          example: Smith
        employee_id:
          type: string
          example: E007
        display_picture:
          $ref: '#/components/schemas/DisplayPicture'
        job_title:
          type: object
          nullable: true
          properties:
            id:
              type: string
            name:
              type: string
        location:
          type: object
          nullable: true
          properties:
            id:
              type: string
            name:
              type: string
        departments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              is_admin:
                type: boolean
                nullable: true
        business_unit:
          type: array
          items:
            type: object
        education:
          type: string
          nullable: true
        about_me:
          type: string
          nullable: true
        phone_number:
          type: string
          nullable: true
        secondary_phone_number:
          type: string
          nullable: true
        level:
          type: string
          nullable: true
        joining_date:
          type: string
          nullable: true
        birthdate:
          type: string
          nullable: true
        promotion_date:
          type: string
          nullable: true
        review_date:
          type: string
          nullable: true
        employee_type:
          type: string
          nullable: true
        primary_reporter:
          nullable: true
          type: object
        direct_reports:
          type: array
          items:
            $ref: '#/components/schemas/UserRef'
        hr_managers:
          type: array
          items:
            $ref: '#/components/schemas/UserRef'
        secondary_managers:
          type: array
          items:
            $ref: '#/components/schemas/UserRef'
        custom_attributes:
          type: object
          additionalProperties: true
          description: Organization-specific custom attributes keyed by attribute_key
    UserPermissionsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
    BlockReasonCode:
      type: object
      properties:
        code:
          type: string
          example: involuntary
        display_text:
          type: string
          example: Involuntary
        description:
          type: string
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        size:
          type: integer
          example: 25
        has_more:
          type: boolean
          example: false
        total_records:
          type: integer
          example: 42
    UserSingleResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/User'
    UserListResponse:
      type: object
      properties:
        success:
          type: boolean
        pagination:
          $ref: '#/components/schemas/Pagination'
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
    ErrorResponse:
      type: object
      properties:
        error_type:
          type: string
          enum:
          - api_connection_error
          - authentication_error
          - invalid_request_error
          - validation_error
          example: validation_error
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    UserRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        first_name:
          type: string
        middle_name:
          type: string
          nullable: true
        last_name:
          type: string
        display_picture:
          $ref: '#/components/schemas/DisplayPicture'
        is_admin:
          type: boolean
          nullable: true
    DisplayPicture:
      type: object
      properties:
        large:
          type: string
          format: uri
          nullable: true
        medium:
          type: string
          format: uri
          nullable: true
        small:
          type: string
          format: uri
          nullable: true
        original:
          type: string
          format: uri
          nullable: true
        reduced:
          type: string
          format: uri
          nullable: true
    Permission:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          example: Site Administrator
        is_admin:
          type: boolean
          nullable: true
        description:
          type: string
    UserCreateRequest:
      type: object
      required:
      - first_name
      - last_name
      - email
      properties:
        first_name:
          type: string
        middle_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        employee_id:
          type: string
        joining_date:
          type: string
          format: date
        birth_date:
          type: string
          format: date
        location:
          type: string
          description: ID of the location
        job_title:
          type: string
          description: ID of the job title
        employee_type:
          type: string
        level:
          type: string
        phone_number:
          type: string
        secondary_phone_number:
          type: string
        promotion_date:
          type: string
        review_date:
          type: string
        departments:
          type: array
          items:
            type: string
          description: Array of department IDs
        businesses:
          type: array
          items:
            type: string
          description: Array of business unit IDs
        hr_managers:
          type: array
          items:
            type: string
          description: Array of HR manager user IDs
        secondary_managers:
          type: array
          items:
            type: string
          description: Array of secondary manager user IDs
        manager_id:
          type: string
          description: ID of the primary manager
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
    UserUpdateRequest:
      type: object
      properties:
        first_name:
          type: string
        middle_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        employee_id:
          type: string
        joining_date:
          type: string
          format: date
        birth_date:
          type: string
          format: date
        location:
          type: string
          description: ID of the location
        job_title:
          type: string
          description: ID of the job title
        level:
          type: string
        phone_number:
          type: string
        secondary_phone_number:
          type: string
        promotion_date:
          type: string
        review_date:
          type: string
        departments:
          type: array
          items:
            type: string
        businesses:
          type: array
          items:
            type: string
        hr_managers:
          type: array
          items:
            type: string
        secondary_managers:
          type: array
          items:
            type: string
        manager_id:
          type: string
        custom_attributes:
          type: object
          additionalProperties: true
          description: Custom attributes using their attribute_key as field names
  parameters:
    pageParam:
      name: page
      in: query
      description: Page number (starts at 1)
      schema:
        type: integer
        minimum: 1
        default: 1
    sizeParam:
      name: size
      in: query
      description: Number of records per page (maximum 50)
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 25
    idPathParam:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource
      schema:
        type: string
  securitySchemes:
    clientKeyAuth:
      type: apiKey
      in: header
      name: ClientKey
      description: Client key obtained from the Engagedly portal under Integrations > Engagedly API
    secretKeyAuth:
      type: apiKey
      in: header
      name: SecretKey
      description: Secret key obtained from the Engagedly portal. Shown only once upon generation.