Seismic Users API

openapi: 3.1.0
info:
  title: Seismic Analytics Content Analytics Users API
  description: API for accessing analytics and reporting data on content usage, user engagement, and sales effectiveness within the Seismic platform. Provides insights into how content is being used, which materials are most effective, and how teams are engaging with sales enablement resources.
  version: 2.0.0
  termsOfService: https://seismic.com/terms-of-service/
  contact:
    name: Seismic Support
    url: https://seismic.com/support/
    email: support@seismic.com
  license:
    name: Proprietary
    url: https://seismic.com/terms-of-service/
servers:
- url: https://api.seismic.com/integration/v2
  description: Seismic API v2 Production
security:
- bearerAuth: []
tags:
- name: Users
  description: Operations for managing user accounts.
paths:
  /users:
    get:
      operationId: listUsers
      summary: List Users
      description: Retrieves a list of users in the Seismic platform. Supports filtering by group, role, status, and search query.
      tags:
      - Users
      parameters:
      - name: query
        in: query
        description: Search query to filter users by name or email.
        schema:
          type: string
      - name: groupId
        in: query
        description: Filter users by group membership.
        schema:
          type: string
      - name: roleId
        in: query
        description: Filter users by assigned role.
        schema:
          type: string
      - name: teamId
        in: query
        description: Filter users by team membership.
        schema:
          type: string
      - name: status
        in: query
        description: Filter users by account status.
        schema:
          type: string
          enum:
          - active
          - inactive
          - pending
          - suspended
      - name: sortBy
        in: query
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - name
          - email
          - createdAt
          - lastLoginAt
      - name: sortOrder
        in: query
        description: Sort order direction.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: offset
        in: query
        description: Number of items to skip for pagination.
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Maximum number of items to return.
        schema:
          type: integer
          default: 25
          maximum: 100
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  totalCount:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createUser
      summary: Create a User
      description: Creates a new user account in the Seismic platform. An invitation email will be sent to the user.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - firstName
              - lastName
              properties:
                email:
                  type: string
                  format: email
                  description: Email address for the user account.
                firstName:
                  type: string
                  description: First name of the user.
                lastName:
                  type: string
                  description: Last name of the user.
                title:
                  type: string
                  description: Job title of the user.
                department:
                  type: string
                  description: Department the user belongs to.
                roleId:
                  type: string
                  description: ID of the role to assign to the user.
                groupIds:
                  type: array
                  items:
                    type: string
                  description: IDs of groups to add the user to.
                teamId:
                  type: string
                  description: ID of the team to assign the user to.
                sendInvitation:
                  type: boolean
                  description: Whether to send an invitation email to the user.
                  default: true
      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':
          description: Conflict. A user with this email already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /users/{userId}:
    get:
      operationId: getUser
      summary: Get a User
      description: Retrieves details of a specific user by their ID.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      responses:
        '200':
          description: User details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      operationId: updateUser
      summary: Update a User
      description: Updates the profile or settings of a specific user.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  description: Updated first name.
                lastName:
                  type: string
                  description: Updated last name.
                title:
                  type: string
                  description: Updated job title.
                department:
                  type: string
                  description: Updated department.
                roleId:
                  type: string
                  description: ID of the new role to assign.
                status:
                  type: string
                  description: Updated account status.
                  enum:
                  - active
                  - inactive
                  - suspended
                teamId:
                  type: string
                  description: ID of the team to assign the user to.
      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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteUser
      summary: Delete a User
      description: Deactivates and removes a user account from the Seismic platform. Content owned by the user may be reassigned.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      - name: reassignTo
        in: query
        description: ID of the user to reassign content to.
        schema:
          type: string
      responses:
        '204':
          description: User deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /users/{userId}/groups:
    get:
      operationId: getUserGroups
      summary: Get User Groups
      description: Retrieves the groups that a specific user belongs to.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      responses:
        '200':
          description: List of groups the user belongs to.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
                  totalCount:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    put:
      operationId: setUserGroups
      summary: Set User Group Memberships
      description: Replaces the user's group memberships with the specified set of groups.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - groupIds
              properties:
                groupIds:
                  type: array
                  items:
                    type: string
                  description: IDs of the groups to assign to the user.
      responses:
        '200':
          description: User group memberships updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Forbidden:
      description: Forbidden. The authenticated user does not have permission to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too many requests. Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Retry-After:
          description: Number of seconds to wait before making another request.
          schema:
            type: integer
    Unauthorized:
      description: Unauthorized. Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request. The request was invalid or cannot be processed.
      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'
  schemas:
    Group:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the group.
        name:
          type: string
          description: Name of the group.
        description:
          type: string
          description: Description of the group.
        parentId:
          type: string
          description: ID of the parent group.
        memberCount:
          type: integer
          description: Number of members in the group.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the group was created.
        modifiedAt:
          type: string
          format: date-time
          description: Timestamp when the group was last modified.
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the user.
        email:
          type: string
          format: email
          description: Email address of the user.
        firstName:
          type: string
          description: First name of the user.
        lastName:
          type: string
          description: Last name of the user.
        displayName:
          type: string
          description: Display name of the user.
        title:
          type: string
          description: Job title of the user.
        department:
          type: string
          description: Department the user belongs to.
        roleId:
          type: string
          description: ID of the assigned role.
        roleName:
          type: string
          description: Name of the assigned role.
        teamId:
          type: string
          description: ID of the team the user belongs to.
        teamName:
          type: string
          description: Name of the team the user belongs to.
        status:
          type: string
          description: Account status.
          enum:
          - active
          - inactive
          - pending
          - suspended
        avatarUrl:
          type: string
          format: uri
          description: URL of the user's avatar image.
        lastLoginAt:
          type: string
          format: date-time
          description: Timestamp of the user's last login.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the user account was created.
        modifiedAt:
          type: string
          format: date-time
          description: Timestamp when the user account was last modified.
    Error:
      type: object
      properties:
        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
  parameters:
    userId:
      name: userId
      in: path
      required: true
      description: Unique identifier of the user.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer Token. Obtain tokens through the Seismic authentication flow. See https://developer.seismic.com/seismicsoftware/docs/authentication