TalentLMS User API

openapi: 3.0.0
info:
  title: TalentLMS Public Batch Actions User API
  description: "TalentLMS offers a range of API endpoints and resources designed to integrate TalentLMS with your internal systems seamlessly. It is organized around Representational State Transfer (REST) and is built to leverage standard HTTP features such as HTTP authentication and HTTP response codes, ensuring seamless integration. All API responses, including error messages, are consistently formatted in JSON for easy parsing and handling.\n\nIf your TalentLMS domain is called “samples”, then the API endpoint for your domain is [<code>https://samples.talentlms.com/api/v2</code>](https://samples.talentlms.com/api).\n\nThe current version of the API consumes data – information about users, courses, categories, groups, branches, and general details about your domain. Apart from that, via the API you can log in / sign up a user in your domain, enroll a user in a course, and much more. Please make sure, that you are accessing the URLs below, under HTTPs connections, otherwise, you will receive an error.\n\n## \U0001F680 **Getting Started Guide**\n\nTo start using the TalentLMS API, you must first [enable the API and generate a valid API](https://help.talentlms.com/hc/en-us/articles/9651527213468-Can-I-integrate-my-site-with-TalentLMS-Do-you-offer-an-API) key from the portal's settings (Account & Settings > Integrations > API).\n\n**Keep in mind:**\n\n- The pagination limit of each request is 100.\n    \n- The API has rate and usage limits (e.g. 2000 requests per hour).\n    \n- The API returns request responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key (All calls must have an Accept: application/json header value).\n    \n- In each request you must add the desired version of the API by adding the header option with the key `X-API-Version` and value (the format of the version must be `YYYY-MM-DD`).\n    \n## \U0001F510 Authentication\n\nAll of the requests require authentication. Our API uses the `API Key` authorization method, with key `X-API-Key` and value `your_api_key`. You can always fill these fields in the global variables or create an environment and insert them there.\n\n### ⛔️ Authentication error response\n\nYou will receive an HTTP 401 Unauthorized response code if the API key is missing, incorrectly formatted, or invalid.\n\n### ✅ API Responses\n\nTalentLMS API uses HTTP response codes to indicate the success or failure of requests. Specifically, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided arguments (e.g. instead of an integer a string is supplied), and the 500 error code indicates an internal TalentLMS error. Please be aware that you will receive an error too, in case you try to access an endpoint via non HTTPs connection.\n\nAll errors return JSON consisting of a type (invalid_request_error or api_error) and a message describing the error.\n\n| **Code** | **Description** |\n| --- | --- |\n| 200 | The request was executed properly and a JSON response is returned. |\n| 204 | No content, and the operation was executed successfully. |\n| 400 | A required parameter is missing or an invalid type (e.g. a string) was supplied instead of an integer. |\n| 401 | Invalid API key provided. |\n| 403 | API is not enabled for the specified domain or the domain is currently inactive. |\n| 404 | The requested resource (e.g. user) does not exist. |\n| 422 | Malformed response. |\n| 429 | The API request rate limit has been exceeded. |\n| 500 | Internal server error. |\n\n### \U0001F6D1 Rate Limits\n\nRate limits represent the maximum number of API requests that are permitted to be made  \nper hour. These limits depend on your subscription plan and are as follows:\n\n| **Plan** | **Limit** |\n| --- | --- |\n| Core | 2.000 |\n| Grow | 10.000 |\n| Pro | 10.000 |\n| Small | 2.000 |\n| Basic | 2.000 |\n| Plus | 10.000 |\n| Premium | 10.000 |\n| Custom | Contact us so we can create a plan that fits your needs |\n\nRegardless of the total API requests per hour provisioned per customer, each customer's API requests should not exceed the rate of 200 API calls per 5 seconds. The following headers are included in API responses to help manage rate limits:\n\n- **`X-RateLimit-Limit`**: The maximum number of requests allowed in the current time window\n    \n- **`X-RateLimit-Remaining`**: The number of requests left in the current window before hitting the limit\n    \n### \U0001F4C4 Pagination\n\nOur API supports pagination, splitting responses into size-customizable chunks of up to 100 items per request. You can navigate to the first, last, previous, or next page. The endpoints that support pagination return a list formatted as shown below:\n\n``` json\n{\n        \"self\": \"https://example.talentlms.com/api/v2/users?page[number]=1&page[size]=10\",\n        \"first\": \"https://example.talentlms.com/api/v2/users?page[number]=1&page[size]=10\",\n        \"last\": \"https://example.talentlms.com/api/v2/users?page[number]=4&page[size]=10\",\n        \"prev\": \"https://example.talentlms.com/api/v2/users?page[number]=1&page[size]=10\",\n        \"next\": \"https://example.talentlms.com/api/v2/users?page[number]=2&page[size]=10\"\n}\n\n ```"
  version: 1.0.0
servers:
- url: https://your-domain.talentlms.com
security:
- apikeyAuth: []
tags:
- name: User
paths:
  /api/v2/users:
    get:
      tags:
      - User
      summary: Get users
      description: Returns a paginated list of users. Supports filtering by keyword, status, login, email, last_updated, branch_id, group_id, integration, and custom_field_value.
      operationId: getUsers
      parameters:
      - name: X-API-Version
        in: header
        required: false
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: filter[status][eq]
        in: query
        description: Filter by user status
        required: false
        schema:
          type: string
          enum:
          - active
          - inactive
      - name: filter[login][eq]
        in: query
        description: Filter by exact login match
        required: false
        schema:
          type: string
      - name: filter[email][eq]
        in: query
        description: Filter by exact email match
        required: false
        schema:
          type: string
      - name: filter[keyword][like]
        in: query
        description: Search across name, surname, login, and email
        required: false
        schema:
          type: string
      - name: filter[last_updated][gte]
        in: query
        description: Filter users updated on or after this date (ISO 8601)
        required: false
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00'
      - name: filter[last_updated][lte]
        in: query
        description: Filter users updated on or before this date (ISO 8601)
        required: false
        schema:
          type: string
          format: date-time
        example: '2024-12-31T23:59:59'
      - name: filter[branch_id][eq]
        in: query
        description: Filter users belonging to a specific branch
        required: false
        schema:
          type: integer
      - name: filter[group_id][eq]
        in: query
        description: Filter users belonging to a specific group
        required: false
        schema:
          type: integer
      - name: filter[integration][eq]
        in: query
        description: Filter users linked to a specific integration
        required: false
        schema:
          type: string
      - name: filter[custom_field_value][eq]
        in: query
        description: Filter users by a custom field value
        required: false
        schema:
          type: string
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  _data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserListItem'
                  _links:
                    $ref: '#/components/schemas/PaginationLinks'
                  _meta:
                    $ref: '#/components/schemas/PaginationMeta'
                type: object
    post:
      tags:
      - User
      summary: Create a user
      description: '### Create a user


        This endpoint accepts a JSON body containing the properties of the user to be created (e.g., `name`, `email`, `password`, etc.). Validates all required fields and returns the newly created user object upon success.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                name: <string|required>
                surname: <string|required>
                login: <string|required>
                email: <email|required>
                timezone: <timezone>
                locale: <locale>
                email_notifications: <boolean>
                user_type_id: <integer>
                status: <boolean>
                password: <string|required>
                description: <null|string>
                credits: <null|float>
                deactivation_date: <null|date>
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/users/{id}:
    get:
      tags:
      - User
      summary: Get a user
      description: Retrieves the complete profile details of a specific user. To successfully fetch a user, include the user's unique ID as a path parameter in the request URL. If the request is valid and the user exists, the API returns the full set of user details in the response.
      operationId: getUserById
      parameters:
      - name: id
        in: path
        description: The ID of the user
        required: true
        schema:
          type: integer
      - name: X-API-Version
        in: header
        required: false
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  _data:
                    properties:
                      id:
                        type: integer
                      login:
                        type: string
                      name:
                        type: string
                      surname:
                        type: string
                      email:
                        type: string
                        format: email
                      credits:
                        type: number
                        format: float
                        nullable: true
                      description:
                        properties:
                          html:
                            type: string
                          text:
                            type: string
                        type: object
                        nullable: true
                      avatar:
                        properties:
                          default:
                            type: string
                            format: uri
                          sm:
                            type: string
                            format: uri
                            nullable: true
                          md:
                            type: string
                            format: uri
                            nullable: true
                          lg:
                            type: string
                            format: uri
                            nullable: true
                          xl:
                            type: string
                            format: uri
                            nullable: true
                        type: object
                        nullable: true
                      custom_fields:
                        type: array
                        items:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                            value:
                              type: string
                              nullable: true
                            type:
                              type: string
                              enum:
                              - text
                              - dropdown
                              - checkbox
                              - date
                          type: object
                      email_notifications:
                        type: boolean
                      timezone:
                        type: string
                      locale:
                        type: string
                      user_type:
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                          is_default:
                            type: boolean
                            nullable: true
                        type: object
                      status:
                        type: string
                        enum:
                        - active
                        - inactive
                      deactivation_date:
                        type: string
                        format: date-time
                        nullable: true
                      available_types:
                        type: array
                        items:
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                            is_default:
                              type: boolean
                              nullable: true
                          type: object
                    type: object
                type: object
    patch:
      tags:
      - User
      summary: Update a user
      description: '### Update a user


        Provide the user ID and updated fields to change user info and you will receive a 204 success message.


        | Name | Type | Required | Description | Example Value |

        | --- | --- | --- | --- | --- |

        | name | string | true | Maximum character limit: 191 characters. | "John" |

        | surname | string | true | Maximum character limit: 191 characters. | "Doe" |

        | login | string | true | Maximum character limit: 191 characters. | "johndoe123" |

        | email | email | true | It has to be a valid email format and structure. Maximum character limit: 191 characters. The email has to be unique. | "john@example.com" |

        | description | string | true | Maximum character limit: 191 characters. | "A short bio" |

        | timezone | string | true | Maximum character limit: 191 characters. | "UTC" |

        | locale | string | true | Maximum character limit: 191 characters. | "en-US" |

        | email_notifications | boolean | true | Enable or disable email notifications. | true |

        | user_type_id | integer | true | ID representing the user''s type. | 1 |

        | active | boolean | true | Indicates if the account is active. | true |

        | deactivation_date | date | true | Date when the account was deactivated. | "2024-01-01" |

        | current_password | string | true | Maximum character limit: 191 characters. | "currentPass123" |

        | password | string | true | Maximum character limit: 191 characters. | "newPass456" |

        | credits | float | true | Amount of user credits. | 11 |'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                name: <string|optional>
                surname: <string|optional>
                login: <string|optional>
                email: <email|optional>
                description: <string|optional>
                timezone: <string|timezone|optional>
                locale: <string|optional>
                email_notifications: <boolean|optional>
                user_type_id: <integer|optional>
                status: <enum|required>
                deactivation_date: <string|YYYY-MM-DD|optional>
                current_password: <string|optional>
                password: <string|optional>
                credits: <integer|optional>
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the user
        schema:
          type: integer
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
    delete:
      tags:
      - User
      summary: Delete a user
      description: '### Delete a user


        Permanently deletes a specific user from your TalentLMS account. To successfully remove a user, include the user''s unique ID as a path parameter in the request URL. If the request is valid and the user exists, the API deletes the user and returns a confirmation response.'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the user
        schema:
          type: integer
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/course-progress:
    get:
      tags:
      - User
      summary: Get user's course progress
      description: '### Get user''s course progress


        Retrieve a user''s progress in a specific course by providing both `user_id` and `course_id` as query parameters, and receive JSON data about their course progress, completion status, and score.'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: Accept
        in: header
        schema:
          type: string
        example: application/json
      - name: user_id
        in: query
        schema:
          type: string
        example: <integer>
      - name: course_id
        in: query
        schema:
          type: string
        example: <integer>
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
    delete:
      tags:
      - User
      summary: Reset user's course progress
      description: '### Reset user''s course progress


        Provide user ID and course ID to reset the user''s progress for a course, with a success (no content) or error response.'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: user_id
        in: query
        schema:
          type: string
        example: <integer>
      - name: course_id
        in: query
        schema:
          type: string
        example: <integer>
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/user-fields:
    get:
      tags:
      - User
      summary: Get user custom fields
      description: '### Get user custom fields


        Get all custom fields defined for users by making a simple authenticated GET request, and receive their definitions as a JSON array.'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/unit-progress:
    get:
      tags:
      - User
      summary: Get user's unit progress
      description: '### Get user''s unit progress


        Retrieve a user''s progress in a specific unit by supplying `user_id` and `unit_id` as query parameters, and receive JSON data about the unit''s progress, such as status, score, and timestamps.'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: user_id
        in: query
        schema:
          type: string
        example: <integer>
      - name: unit_id
        in: query
        schema:
          type: string
        example: <integer>
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/users/:id/login:
    get:
      tags:
      - User
      summary: Login user
      description: '### Login user


        Logs in a specific user to the portal. To successfully log in a user, provide the user''s unique ID in the request. If the request is valid and the user exists, the system initiates a new session and logs the user into the portal.'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/users/:id/logout:
    post:
      tags:
      - User
      summary: Logout user
      description: '### Logout user


        Logs out a specific user from the portal by terminating their active session. To successfully log out a user, provide the user’s unique ID in the request. If the request is valid and the user exists, the system immediately invalidates the user’s current session and logs them out of the portal.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                next: ''
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/users/:id/online-status:
    get:
      tags:
      - User
      summary: Get user online status
      description: '### Get user online status


        Retrieves the current online status of a specific user. To check whether a user is currently online, provide the user’s unique ID in the request. If the request is valid and the user exists, the API returns the user’s online status.'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/password-reset:
    post:
      tags:
      - User
      summary: Reset user's password
      description: '### Reset user''s password


        Reset a user''s password by providing the user''s login in the path and a base64-encoded redirect URL as a query parameter, returning a 204 No Content response upon successful password reset request.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                login: <login>
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: redirect_url
        in: query
        schema:
          type: string
        example: <base64_encoded_url>
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/users/:email/username-recovery:
    post:
      tags:
      - User
      summary: Recover username
      description: '### Recover username


        The system sends an email to the user (using the specified attribute, such as their login or email), which includes their username; the user can provide a custom portal URL (`domain_url`), and if not provided, the system will use the default portal URL.'
      requestBody:
        content: {}
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: domain_url
        in: query
        schema:
          type: string
        example: <base64_encoded_url>
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
  /api/v2/users/{id}/groups:
    get:
      tags:
      - User
      summary: Get user groups
      description: Retrieves the groups assigned to a specific user. Include the user's unique ID as a path parameter. Returns a list of groups with their ID and name.
      operationId: getUserGroups
      parameters:
      - name: id
        in: path
        description: The ID of the user
        required: true
        schema:
          type: integer
      - name: X-API-Version
        in: header
        required: false
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  _data:
                    properties:
                      groups:
                        type: array
                        items:
                          required:
                          - id
                          - name
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                    type: object
                type: object
  /api/v2/users/{id}/branches:
    get:
      tags:
      - User
      summary: Get user branches
      description: Retrieves the branches assigned to a specific user. Include the user's unique ID as a path parameter. Returns a list of branches with their ID and name.
      operationId: getUserBranches
      parameters:
      - name: id
        in: path
        description: The ID of the user
        required: true
        schema:
          type: integer
      - name: X-API-Version
        in: header
        required: false
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  _data:
                    properties:
                      branches:
                        type: array
                        items:
                          required:
                          - id
                          - name
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                    type: object
                type: object
  /api/v2/users/{id}/courses:
    get:
      tags:
      - User
      summary: Get user courses
      description: Retrieves the courses assigned to a specific user. Include the user's unique ID as a path parameter. Returns a list of courses with their ID and name.
      operationId: getUserCourses
      parameters:
      - name: id
        in: path
        description: The ID of the user
        required: true
        schema:
          type: integer
      - name: X-API-Version
        in: header
        required: false
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  _data:
                    properties:
                      courses:
                        type: array
                        items:
                          required:
                          - id
                          - name
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                    type: object
                type: object
  /api/v2/users/{id}/resources:
    get:
      tags:
      - User
      summary: Get user resources
      description: 'Retrieves all resources assigned to a specific user: branches, groups, courses, and certificates.'
      operationId: getUserResources
      parameters:
      - name: id
        in: path
        description: The ID of the user
        required: true
        schema:
          type: integer
      - name: X-API-Version
        in: header
        required: false
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  _data:
                    properties:
                      branches:
                        type: array
                        items:
                          required:
                          - id
                          - name
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                      groups:
                        type: array
                        items:
                          required:
                          - id
                          - name
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                      courses:
                        type: array
                        items:
                          required:
                          - id
                          - name
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                      certificates:
                        type: array
                        items:
                          required:
                          - id
                          - name
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                          type: object
                    type: object
                type: object
  /api/v2/users/{id}/gamification:
    get:
      tags:
      - User
      summary: Get a user's gamification data
      description: "### Returns a user's gamification sub-resource (points, level, and badges).\n     *     Returns 404 when gamification is disabled for the portal, or when the user does not exist.\n     *     Each badge contains: name, type, image_url, criteria, issued_on (unix timestamp) and badge_set_id."
      operationId: getUserGamification
      parameters:
      - name: id
        in: path
        description: The ID of the user
        required: true
        schema:
          type: integer
      - name: X-API-Version
        in: header
        required: false
        schema:
          type: st

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talentlms/refs/heads/main/openapi/talentlms-user-api-openapi.yml