Showpad Usergroups API

openapi: 3.2.0
info:
  title: Showpad Usergroups API
  version: '3'
  termsOfService: https://www.showpad.com/terms-of-service
  contact:
    name: Showpad
    email: support@showpad.com
    url: https://help.showpad.com/hc/en-us/requests/new
  x-audience: external-partner
servers:
- url: https://{subdomain}.showpad.biz/api/v3/
  description: Production server
  x-environment: production
  variables:
    subdomain:
      default: customer
      description: Showpad customer subdomain
security:
- oAuth: []
- bearerAuth: []
tags:
- name: usergroups
  description: ''
paths:
  /usergroups.json:
    get:
      deprecated: false
      tags:
      - usergroups
      operationId: get_usergroups
      description: Generates a list of Usergroup items
      summary: /usergroups.json
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                properties:
                  meta:
                    type: object
                    properties:
                      code:
                        type: integer
                        format: int32
                      message:
                        type: string
                      serverTime:
                        type: string
                        format: date-time
                      lastUpdatedTime:
                        type: string
                        format: date-time
                      requestRateLimit:
                        type: integer
                        format: int32
                      requestRateLimitReset:
                        type: integer
                        format: int32
                      requestsRemaining:
                        type: integer
                        format: int32
                      location:
                        type: string
                        format: link
                      userTimezone:
                        type: object
                        properties:
                          offset:
                            type: string
                          name:
                            type: string
                  response:
                    type: object
                    properties:
                      count:
                        description: Total number of results.
                        type: integer
                        format: int32
                        example: 20
                      items:
                        type: array
                        description: List of resources.
                        items:
                          type: object
                          properties:
                            id:
                              description: Unique identifier for the resource
                              type: string
                            resourcetype:
                              description: The type of resource
                              type: string
                            href:
                              description: Location of the resource
                              type: string
                              format: link
                            name:
                              description: Name of the usergroup
                              type: string
                            description:
                              description: Description of the usergroup
                              type: string
                            externalId:
                              description: External ID of the usergroup as used in the source application
                              type:
                              - string
                              - 'null'
                            updatedAt:
                              description: The date that the usergroup was updated
                              type: string
                              format: date-time
                            createdAt:
                              description: The date that the usergroup was created
                              type: string
                              format: date-time
                            divisions:
                              description: The division linked to this usergroup
                              type: object
                              properties:
                                href:
                                  type: string
                                  format: link
                            users:
                              description: The users linked to this usergroup
                              type: object
                              properties:
                                href:
                                  type: string
                                  format: link
                            anonymizedUserData:
                              description: Displays if this groups has anonymized data.
                              type: boolean
                            isDefault:
                              description: Default usergroup containing all users.
                              type: boolean
                            userCount:
                              description: The amount of users in this group.
                              type:
                              - integer
                              - 'null'
                              format: int32
                            deactivatedUserCount:
                              description: The amount of deactivated users in this group.
                              type:
                              - integer
                              - 'null'
                              format: int32
                            pendingInvitationUserCount:
                              description: The amount of users in this group for which an invitation is still pending.
                              type:
                              - integer
                              - 'null'
                              format: int32
                            neverLoggedInUserCount:
                              description: The amount of users in this group that never logged in.
                              type:
                              - integer
                              - 'null'
                              format: int32
                            numberOfDirectLicenses:
                              description: The number of direct licenses.
                              type:
                              - integer
                              - 'null'
                              format: int32
                            numberOfPartnerLicenses:
                              description: The number of partner licenses.
                              type:
                              - integer
                              - 'null'
                              format: int32
                            numberOfViewOnlyLicenses:
                              description: The number of view only licenses.
                              type:
                              - integer
                              - 'null'
                              format: int32
                            isSynced:
                              description: Show that usergroup is synced
                              type: boolean
                            hasManageGroupsPermission:
                              description: Has permission to manage groups.
                              type:
                              - boolean
                              - 'null'
                            provisionedBy:
                              description: The system that provisioned this usergroup.
                              type:
                              - string
                              - 'null'
      security:
      - bearerAuth: []
      - oAuth:
        - read_user_management
      parameters:
      - name: describe_apis
        description: Describes the different api calls available together with the allowed parameters
        required: false
        in: query
        schema:
          type: boolean
      - name: describe_model
        description: Describes the data model behind the resource including properties and their description
        required: false
        in: query
        schema:
          type: boolean
      - name: expand
        description: Comma separated list of all expanded relationships that need to be retrieved.
        required: false
        in: query
        schema:
          type: string
          enum:
          - experiences
          - managers
          - tags
          - users
      - name: externalId
        description: External ID of the usergroup as used in the source application
        required: false
        in: query
        schema:
          type: string
      - name: fields
        description: Comma separated list of all fields that need to be retrieved.
        required: false
        in: query
        schema:
          type: string
      - name: isSynced
        description: Show that usergroup is synced
        required: false
        in: query
        schema:
          type: boolean
      - name: limit
        description: Sets the maximum number of returned items. The maximum limit is set to 1000. For example, if 'limit' is 0, only 0 items will be retrieved.
        required: false
        in: query
        schema:
          type: integer
          format: int32
          minimum: 0
          maximum: 1000
      - name: method
        description: '''method'' can be used by HTTP clients who are not able to set certain HTTP verbs such as a DELETE of a PUT'
        required: false
        in: query
        schema:
          type: string
          anyOf:
          - title: post
            type: string
      - name: name
        description: Name of the usergroup
        required: false
        in: query
        schema:
          type: string
      - name: offset
        description: Set the offset of the returned items.For example, if 'offset' is 5 and 'limit' is 10,  items 6 to 15 will be returned.
        required: false
        in: query
        schema:
          type: integer
          format: int32
          minimum: 0
      - name: sort
        description: The field you want to sort on. Adding a '-' in front of the field name allows you to sort descending. Allowed values are name.
        required: false
        in: query
        schema:
          type: string
      - name: suppress_response_codes
        description: 'This forces the HTTP status code of the response to be set to 200 '
        required: false
        in: query
        schema:
          type: boolean
    post:
      deprecated: false
      tags:
      - usergroups
      operationId: post_usergroups
      description: Create a Usergroup item
      summary: /usergroups.json
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                properties:
                  meta:
                    type: object
                    properties:
                      code:
                        type: integer
                        format: int32
                      message:
                        type: string
                      serverTime:
                        type: string
                        format: date-time
                      lastUpdatedTime:
                        type: string
                        format: date-time
                      requestRateLimit:
                        type: integer
                        format: int32
                      requestRateLimitReset:
                        type: integer
                        format: int32
                      requestsRemaining:
                        type: integer
                        format: int32
                      location:
                        type: string
                        format: link
                      userTimezone:
                        type: object
                        properties:
                          offset:
                            type: string
                          name:
                            type: string
                  response:
                    type: object
                    properties:
                      id:
                        description: Unique identifier for the resource
                        type: string
                      resourcetype:
                        description: The type of resource
                        type: string
                      href:
                        description: Location of the resource
                        type: string
                        format: link
                      name:
                        description: Name of the usergroup
                        type: string
                      description:
                        description: Description of the usergroup
                        type: string
                      externalId:
                        description: External ID of the usergroup as used in the source application
                        type:
                        - string
                        - 'null'
                      updatedAt:
                        description: The date that the usergroup was updated
                        type: string
                        format: date-time
                      createdAt:
                        description: The date that the usergroup was created
                        type: string
                        format: date-time
                      divisions:
                        description: The division linked to this usergroup
                        type: object
                        properties:
                          href:
                            type: string
                            format: link
                      users:
                        description: The users linked to this usergroup
                        type: object
                        properties:
                          href:
                            type: string
                            format: link
                      anonymizedUserData:
                        description: Displays if this groups has anonymized data.
                        type: boolean
                      isDefault:
                        description: Default usergroup containing all users.
                        type: boolean
                      userCount:
                        description: The amount of users in this group.
                        type:
                        - integer
                        - 'null'
                        format: int32
                      deactivatedUserCount:
                        description: The amount of deactivated users in this group.
                        type:
                        - integer
                        - 'null'
                        format: int32
                      pendingInvitationUserCount:
                        description: The amount of users in this group for which an invitation is still pending.
                        type:
                        - integer
                        - 'null'
                        format: int32
                      neverLoggedInUserCount:
                        description: The amount of users in this group that never logged in.
                        type:
                        - integer
                        - 'null'
                        format: int32
                      numberOfDirectLicenses:
                        description: The number of direct licenses.
                        type:
                        - integer
                        - 'null'
                        format: int32
                      numberOfPartnerLicenses:
                        description: The number of partner licenses.
                        type:
                        - integer
                        - 'null'
                        format: int32
                      numberOfViewOnlyLicenses:
                        description: The number of view only licenses.
                        type:
                        - integer
                        - 'null'
                        format: int32
                      isSynced:
                        description: Show that usergroup is synced
                        type: boolean
                      hasManageGroupsPermission:
                        description: Has permission to manage groups.
                        type:
                        - boolean
                        - 'null'
                      provisionedBy:
                        description: The system that provisioned this usergroup.
                        type:
                        - string
                        - 'null'
      security:
      - bearerAuth: []
      - oAuth:
        - write_user_management
      parameters:
      - name: Link
        description: A comma-separated list of '<resourceID>; rel="ResourceType"'
        required: false
        in: header
        schema:
          type: string
      - name: describe_apis
        description: Describes the different api calls available together with the allowed parameters
        required: false
        in: query
        schema:
          type: boolean
      - name: describe_model
        description: Describes the data model behind the resource including properties and their description
        required: false
        in: query
        schema:
          type: boolean
      - name: expand
        description: Comma separated list of all expanded relationships that need to be retrieved.
        required: false
        in: query
        schema:
          type: string
          enum:
          - experiences
          - managers
          - tags
          - users
      - name: fields
        description: Comma separated list of all fields that need to be retrieved.
        required: false
        in: query
        schema:
          type: string
      - name: suppress_response_codes
        description: 'This forces the HTTP status code of the response to be set to 200 '
        required: false
        in: query
        schema:
          type: boolean
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                contentProfiles:
                  type: array
                  items:
                    type: string
                description:
                  type: string
                externalId:
                  type: string
                provisionedBy:
                  type: string
              required:
              - name
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                contentProfiles:
                  type: array
                  items:
                    type: string
                description:
                  type: string
                externalId:
                  type: string
                provisionedBy:
                  type: string
              required:
              - name
  /usergroups/count.json:
    get:
      deprecated: false
      tags:
      - usergroups
      operationId: get_usergroups_count
      description: Retrieve the number of Usergroup items
      summary: /usergroups/count.json
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      code:
                        type: integer
                        format: int32
                      message:
                        type: string
                      serverTime:
                        type: string
                        format: date-time
                      lastUpdatedTime:
                        type: string
                        format: date-time
                      requestRateLimit:
                        type: integer
                        format: int32
                      requestRateLimitReset:
                        type: integer
                        format: int32
                      requestsRemaining:
                        type: integer
                        format: int32
                      location:
                        type: string
                        format: link
                      userTimezone:
                        type: object
                        properties:
                          offset:
                            type: string
                          name:
                            type: string
                  response:
                    type: object
      security:
      - bearerAuth: []
      - oAuth:
        - read_user_management
      parameters:
      - name: describe_apis
        description: Describes the different api calls available together with the allowed parameters
        required: false
        in: query
        schema:
          type: boolean
      - name: describe_model
        description: Describes the data model behind the resource including properties and their description
        required: false
        in: query
        schema:
          type: boolean
      - name: externalId
        description: External ID of the usergroup as used in the source application
        required: false
        in: query
        schema:
          type: string
      - name: isSynced
        description: Show that usergroup is synced
        required: false
        in: query
        schema:
          type: boolean
      - name: name
        description: Name of the usergroup
        required: false
        in: query
        schema:
          type: string
      - name: suppress_response_codes
        description: 'This forces the HTTP status code of the response to be set to 200 '
        required: false
        in: query
        schema:
          type: boolean
  /usergroups/description.json:
    get:
      deprecated: false
      tags:
      - usergroups
      operationId: get_usergroups_description
      description: Generates information about the Usergroup model and available apis
      summary: /usergroups/description.json
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      code:
                        type: integer
                        format: int32
                      message:
                        type: string
                      serverTime:
                        type: string
                        format: date-time
                      lastUpdatedTime:
                        type: string
                        format: date-time
                      requestRateLimit:
                        type: integer
                        format: int32
                      requestRateLimitReset:
                        type: integer
                        format: int32
                      requestsRemaining:
                        type: integer
                        format: int32
                      location:
                        type: string
                        format: link
                      userTimezone:
                        type: object
                        properties:
                          offset:
                            type: string
                          name:
                            type: string
                  response:
                    type: object
      security:
      - bearerAuth: []
      - oAuth:
        - read_user_management
      parameters:
      - name: suppress_response_codes
        description: 'This forces the HTTP status code of the response to be set to 200 '
        required: false
        in: query
        schema:
          type: boolean
  /usergroups/{id1}/divisions/{id2}.json:
    get:
      deprecated: false
      tags:
      - usergroups
      operationId: get_usergroups_id1_divisions_id2
      description: Link or unlink an usergroup with ID = 'id1' to a division with ID = 'id2'
      summary: /usergroups/{id1}/divisions/{id2}.json
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      code:
                        type: integer
                        format: int32
                      message:
                        type: string
                      serverTime:
                        type: string
                        format: date-time
                      lastUpdatedTime:
                        type: string
                        format: date-time
                      requestRateLimit:
                        type: integer
                        format: int32
                      requestRateLimitReset:
                        type: integer
                        format: int32
                      requestsRemaining:
                        type: integer
                        format: int32
                      location:
                        type: string
                        format: link
                      userTimezone:
                        type: object
                        properties:
                          offset:
                            type: string
                          name:
                            type: string
                  response:
                    type: object
      security:
      - bearerAuth: []
      - oAuth:
        - write_user_management
        - write_division_management
      parameters:
      - name: id1
        description: ID of the Usergroup item
        required: true
        in: path
        schema:
          type: string
      - name: id2
        description: ID of the Division item
        required: true
        in: path
        schema:
          type: string
      - name: method
        description: '''method'' can be used by HTTP clients who are not able to set certain HTTP verbs such as a DELETE of a PUT'
        required: true
        in: query
        schema:
          type: string
          anyOf:
          - title: link
            type: string
          - title: unlink
            type: string
      - name: describe_apis
        description: Describes the different api calls available together with the allowed parameters
        required: false
        in: query
        schema:
          type: boolean
      - name: describe_model
        description: Describes the data model behind the resource including properties and their description
        required: false
        in: query
        schema:
          type: boolean
      - name: suppress_response_codes
        description: 'This forces the HTTP status code of the response to be set to 200 '
        required: false
        in: query
        schema:
          type: boolean
  /usergroups/{id1}/divisions/{id2}/link.json:
    post:
      deprecated: false
      tags:
      - usergroups
      operationId: link_usergroups_id1_divisions_id2_link
      description: Link a usergroup with ID = 'id1' to a division with ID = 'id2'
      summary: /usergroups/{id1}/divisions/{id2}/link.json
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      code:
                        type: integer
                        format: int32
                      message:
                        type: string
                      serverTime:
                        type: string
                        format: date-time
                      lastUpdatedTime:
                        type: string
                        format: date-time
                      requestRateLimit:
                        type: integer
                        format: int32
                      requestRateLimitReset:
                        type: integer
                        format: int32
                      requestsRemaining:
                        type: integer
                        format: int32
                      location:
                        type: string
                        format: link
                      userTimezone:
                        type: object
                        properties:
                          offset:
                            type: string
                          name:
                            type: string
                  response:
                    type: object
      security:
      - bearerAuth: []
      - oAuth:
        - write_user_management
        - write_division_management
      parameters:
      - name: id1
        description: ID of the Usergroup item
        required: true
        in: path
        schema:
          type: string
      - name: id2
        description: ID of the Division item
        required: true
        in: path
        schema:
          type: string
      - name: describe_apis
        description: Describes the different api calls available together with the allowed parameters
        required: false
        in: query
        schema:
          type: boolean
      - name: describe_model
        description: Describes the data model behind the resource including properties and their description
        required: false
        in: query
        schema:
          type: boolean
      - name: suppress_response_codes
        description: 'This forces the HTTP status code of the response to be set to 200 '
        required: false
        in: query
        schema:
          type: boolean
  /usergroups/{id1}/divisions/{id2}/unlink.json:
    post:
      deprecated: false
      tags:
      - usergroups
      operationId: unlink_usergroups_id1_divisions_id2_unlink
      description: Unlink a usergroup with ID = 'id1' from a division with ID = 'id2'
      summary: /usergroups/{id1}/divisions/{id2}/unlink.json
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      code:
                        type: integer
                        format: int32
                      message:
                        type: string
                      serverTime:
                        type: string
                        format: date-time
                      lastUpdatedTime:
                        type: string
                        format: date-time
                      requestRateLimit:
                        type: integer
                        format: int32
                      requestRateLimitReset:
                        type: integer
                        format: int32
                      requestsRemaining:
                        type: integer
                        format: int32
                      location:
                        type: string
                        format: link
                      userTimezone:
                        type: object
                        properties:
                          offset:
                            type: string
                          name:
                            type: string
                  response:
                    type: object
      security:
      - bearerAuth: []
      - oAuth:
        - write_user_management
        - write_division_management
      parameters:
      - name: id1
        description: ID of the Usergroup item
        required

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