OpenAPI Specification
openapi: 3.0.3
info:
title: Workleap Attributes Users 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: Users
description: User management and provisioning
paths:
/users/activate:
post:
operationId: activateUsers
summary: Activate users
description: Update users state to active
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserStateChangeRequest'
responses:
'200':
description: Users activated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserStateChangeResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/users:
post:
operationId: createUser
summary: Create a user
description: Create a user in an organization
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
/users/deactivate:
post:
operationId: deactivateUsers
summary: Deactivate users
description: Update users state to deactivated
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserStateChangeRequest'
responses:
'200':
description: Users deactivated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserStateChangeResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/users/{userId}:
get:
operationId: getUser
summary: Get a user
description: Get a user from an organization
tags:
- Users
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 the user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateUser
summary: Update a user
description: Update a user in an organization
tags:
- Users
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:
$ref: '#/components/schemas/UpdateUserRequest'
responses:
'200':
description: User updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteUser
summary: Delete a user
description: Delete a user in an organization
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the user
responses:
'204':
description: User deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/users/search:
post:
operationId: searchUsers
summary: Search users
description: Search users from an organization
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserSearchRequest'
responses:
'200':
description: Successful response with matching users
content:
application/json:
schema:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
totalCount:
type: integer
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/users/{userId}/avatar:
put:
operationId: updateUserAvatar
summary: Update a user avatar
description: Upload an avatar for a user identified by user ID
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the user
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: The avatar image file
required:
- image
responses:
'200':
description: Avatar updated successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/users/avatar:
put:
operationId: updateUserAvatarByEmail
summary: Update a user avatar by email
description: Upload an avatar for a user identified by the image filename (email address)
tags:
- Users
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: The avatar image file named after the user's email address
required:
- image
responses:
'200':
description: Avatar updated successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
Conflict:
description: Conflict - resource already exists
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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'
schemas:
UserStateChangeRequest:
type: object
required:
- userIds
properties:
userIds:
type: array
items:
type: string
format: uuid
description: List of user IDs to activate or deactivate
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
UserSearchRequest:
type: object
properties:
query:
type: string
description: Search query for user name or email
status:
type: string
enum:
- active
- deactivated
description: Filter by user status
page:
type: integer
default: 1
description: Page number for pagination
pageSize:
type: integer
default: 25
description: Number of results per page
UpdateUserRequest:
type: object
properties:
firstName:
type: string
description: The user's first name
lastName:
type: string
description: The user's last name
jobTitle:
type: string
description: The user's job title
department:
type: string
description: The user's department
managerId:
type: string
format: uuid
description: The user ID of the user's manager
User:
type: object
properties:
userId:
type: string
format: uuid
description: The unique identifier of the user
email:
type: string
format: email
description: The user's email address
firstName:
type: string
description: The user's first name
lastName:
type: string
description: The user's last name
status:
type: string
enum:
- active
- deactivated
description: The user's account status
jobTitle:
type: string
description: The user's job title
department:
type: string
description: The user's department
managerId:
type: string
format: uuid
description: The user ID of the user's manager
createdAt:
type: string
format: date-time
description: When the user was created
updatedAt:
type: string
format: date-time
description: When the user was last updated
CreateUserRequest:
type: object
required:
- email
- firstName
- lastName
properties:
email:
type: string
format: email
description: The user's email address
firstName:
type: string
description: The user's first name
lastName:
type: string
description: The user's last name
jobTitle:
type: string
description: The user's job title
department:
type: string
description: The user's department
managerId:
type: string
format: uuid
description: The user ID of the user's manager
UserStateChangeResponse:
type: object
properties:
succeeded:
type: array
items:
type: string
format: uuid
description: User IDs that were successfully updated
failed:
type: array
items:
type: object
properties:
userId:
type: string
format: uuid
reason:
type: string
securitySchemes:
SubscriptionKey:
type: apiKey
in: header
name: workleap-subscription-key
description: API key for authenticating requests to the Workleap API