openapi: 3.0.3
info:
  title: Workleap Attributes API
  description: 'The Workleap REST API provides programmatic access to user and group management, provisioning workflows, engagement scores, pulse survey feedback, GoodVibes recognition data, and organizational attributes across the Workleap platform. It supports both one-time management actions and recurring HRIS-synced provisioning via JSON or CSV-based connections. Authentication uses an API key passed via the workleap-subscription-key header, and API access is available on the Pro and Enterprise subscription plans.

    '
  version: 1.0.0
  contact:
    url: https://docs.api.workleap.com/docs/getting-started
  termsOfService: https://workleap.com/legal/terms-of-service
  license:
    name: Proprietary
servers:
- url: https://api.workleap.com/public
  description: Workleap Production API
security:
- SubscriptionKey: []
tags:
- name: Attributes
  description: User and system attribute management
paths:
  /attributes:
    get:
      operationId: getAttributeDefinitions
      summary: Get system attribute values
      description: Get attributes for an organization
      tags:
      - Attributes
      responses:
        '200':
          description: Successful response with system attributes
          content:
            application/json:
              schema:
                type: object
                properties:
                  attributes:
                    type: array
                    items:
                      $ref: '#/components/schemas/AttributeDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /users/{userId}/attributes:
    get:
      operationId: getUserAttributes
      summary: Get a user system attribute values
      description: Get system attributes for a user
      tags:
      - Attributes
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier of the user
      responses:
        '200':
          description: Successful response with user attributes
          content:
            application/json:
              schema:
                type: object
                properties:
                  attributes:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserAttribute'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: modifyUserAttributes
      summary: Modify user system attributes
      description: Modify a user's system attributes in an organization
      tags:
      - Attributes
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier of the user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                attributes:
                  type: array
                  items:
                    $ref: '#/components/schemas/UserAttributePatch'
      responses:
        '200':
          description: User attributes updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  attributes:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserAttribute'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    UserAttributePatch:
      type: object
      required:
      - attributeId
      - value
      properties:
        attributeId:
          type: string
          description: The unique identifier of the attribute to update
        value:
          description: The new value for the attribute
    UserAttribute:
      type: object
      properties:
        attributeId:
          type: string
          description: The unique identifier of the attribute
        name:
          type: string
          description: The name of the attribute
        value:
          description: The value of the attribute (type varies)
    AttributeDefinition:
      type: object
      properties:
        attributeId:
          type: string
          description: The unique identifier of the attribute
        name:
          type: string
          description: The name of the attribute
        type:
          type: string
          enum:
          - string
          - number
          - boolean
          - date
          description: The data type of the attribute
        isRequired:
          type: boolean
          description: Whether this attribute is required
  responses:
    Unauthorized:
      description: Unauthorized - missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found - the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden - insufficient permissions or plan restrictions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    SubscriptionKey:
      type: apiKey
      in: header
      name: workleap-subscription-key
      description: API key for authenticating requests to the Workleap API