Box Groups API

openapi: 3.2.0
info:
  title: Box Platform Groups API
  description: Box Platform provides functionality to provide access to content stored within Box. It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://box.dev
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 2.0.0
  x-box-commit-hash: '5819125043'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
security:
- OAuth2Security: []
tags:
- name: Groups
  description: Groups created in an enterprise.
  x-box-tag: groups
paths:
  /groups:
    get:
      operationId: get_groups
      summary: Box List groups for enterprise
      x-box-tag: groups
      tags:
      - Groups
      description: 'Retrieves all of the groups for a given enterprise. The user

        must have admin permissions to inspect enterprise''s groups.'
      parameters:
      - name: filter_term
        description: 'Limits the results to only groups whose `name` starts

          with the search term.'
        in: query
        required: false
        example: Engineering
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: limit
        description: The maximum number of items to return per page.
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          maximum: 1000
      - name: offset
        description: 'The offset of the item at which to begin the response.


          Queries with offset parameter value

          exceeding 10000 will be rejected

          with a 400 response.'
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          default: 0
      responses:
        '200':
          description: 'Returns a collection of group objects. If there are no groups, an

            empty collection will be returned.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Groups'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    post:
      operationId: post_groups
      summary: Box Create group
      tags:
      - Groups
      x-box-tag: groups
      description: 'Creates a new group of users in an enterprise. Only users with admin

        permissions can create new groups.'
      parameters:
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  example: Customer Support
                  description: 'The name of the new group to be created. This name must be unique

                    within the enterprise.'
                provenance:
                  type: string
                  description: 'Keeps track of which external source this group is

                    coming, for example `Active Directory`, or `Okta`.


                    Setting this will also prevent Box admins from editing

                    the group name and its members directly via the Box

                    web application.


                    This is desirable for one-way syncing of groups.'
                  maxLength: 255
                  example: Active Directory
                external_sync_identifier:
                  type: string
                  description: 'An arbitrary identifier that can be used by

                    external group sync tools to link this Box Group to

                    an external group.


                    Example values of this field

                    could be an **Active Directory Object ID** or a **Google

                    Group ID**.


                    We recommend you use of this field in

                    order to avoid issues when group names are updated in

                    either Box or external systems.'
                  example: AD:123456
                description:
                  type: string
                  description: A human readable description of the group.
                  maxLength: 255
                  example: '"Customer Support Group - as imported from Active Directory"'
                invitability_level:
                  type: string
                  example: admins_only
                  description: 'Specifies who can invite the group to collaborate

                    on folders.


                    When set to `admins_only` the enterprise admin, co-admins,

                    and the group''s admin can invite the group.


                    When set to `admins_and_members` all the admins listed

                    above and group members can invite the group.


                    When set to `all_managed_users` all managed users in the

                    enterprise can invite the group.'
                  enum:
                  - admins_only
                  - admins_and_members
                  - all_managed_users
                member_viewability_level:
                  type: string
                  example: admins_only
                  description: "Specifies who can see the members of the group.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n  group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n  enterprise"
                  enum:
                  - admins_only
                  - admins_and_members
                  - all_managed_users
      responses:
        '201':
          description: Returns the new group object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group--Full'
        '409':
          description: 'Returns an error a conflict is stopping the group from being created.


            * `invalid_parameter`: Often returned if the group name is not unique in

            the enterprise.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /groups/{group_id}:
    get:
      operationId: get_groups_id
      summary: Box Get group
      tags:
      - Groups
      x-box-tag: groups
      description: 'Retrieves information about a group. Only members of this

        group or users with admin-level permissions will be able to

        use this API.'
      parameters:
      - name: group_id
        description: The ID of the group.
        example: '57645'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Returns the group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group--Full'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_groups_id
      summary: Box Update group
      tags:
      - Groups
      x-box-tag: groups
      description: 'Updates a specific group. Only admins of this

        group or users with admin-level permissions will be able to

        use this API.'
      parameters:
      - name: group_id
        description: The ID of the group.
        example: '57645'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Customer Support
                  description: 'The name of the new group to be created. Must be unique within the

                    enterprise.'
                provenance:
                  type: string
                  description: 'Keeps track of which external source this group is

                    coming, for example `Active Directory`, or `Okta`.


                    Setting this will also prevent Box admins from editing

                    the group name and its members directly via the Box

                    web application.


                    This is desirable for one-way syncing of groups.'
                  maxLength: 255
                  example: Active Directory
                external_sync_identifier:
                  type: string
                  description: 'An arbitrary identifier that can be used by

                    external group sync tools to link this Box Group to

                    an external group.


                    Example values of this field

                    could be an **Active Directory Object ID** or a **Google

                    Group ID**.


                    We recommend you use of this field in

                    order to avoid issues when group names are updated in

                    either Box or external systems.'
                  example: AD:123456
                description:
                  type: string
                  description: A human readable description of the group.
                  maxLength: 255
                  example: '"Customer Support Group - as imported from Active Directory"'
                invitability_level:
                  type: string
                  example: admins_only
                  description: 'Specifies who can invite the group to collaborate

                    on folders.


                    When set to `admins_only` the enterprise admin, co-admins,

                    and the group''s admin can invite the group.


                    When set to `admins_and_members` all the admins listed

                    above and group members can invite the group.


                    When set to `all_managed_users` all managed users in the

                    enterprise can invite the group.'
                  enum:
                  - admins_only
                  - admins_and_members
                  - all_managed_users
                member_viewability_level:
                  type: string
                  example: admins_only
                  description: "Specifies who can see the members of the group.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n  group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n  enterprise"
                  enum:
                  - admins_only
                  - admins_and_members
                  - all_managed_users
      responses:
        '200':
          description: Returns the updated group object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group--Full'
        '409':
          description: 'Returns an error a conflict is stopping the group from being created.


            * `invalid_parameter`: Often returned if the group name is not unique in

            the enterprise.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_groups_id
      summary: Box Remove group
      tags:
      - Groups
      x-box-tag: groups
      description: 'Permanently deletes a group. Only users with

        admin-level permissions will be able to use this API.'
      parameters:
      - name: group_id
        description: The ID of the group.
        example: '57645'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'A blank response is returned if the group was

            successfully deleted.'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    Group--Mini:
      title: Group (Mini)
      type: object
      x-box-resource-id: group--mini
      x-box-variant: mini
      description: 'Mini representation of a group, including id and name of

        group.'
      allOf:
      - $ref: '#/components/schemas/Group--Base'
      - properties:
          name:
            type: string
            description: The name of the group
            example: Support
          group_type:
            type: string
            description: The type of the group.
            example: managed_group
            enum:
            - managed_group
            - all_users_group
    Groups:
      title: Groups
      type: object
      x-box-resource-id: groups
      x-box-tag: groups
      description: A list of groups.
      allOf:
      - type: object
        description: The part of an API response that describes pagination
        properties:
          total_count:
            description: 'One greater than the offset of the last entry in the entire collection.

              The total number of entries in the collection may be less than

              `total_count`.


              This field is only returned for calls that use offset-based pagination.

              For marker-based paginated APIs, this field will be omitted.'
            example: 5000
            type: integer
            format: int64
          limit:
            description: 'The limit that was used for these entries. This will be the same as the

              `limit` query parameter unless that value exceeded the maximum value

              allowed. The maximum value varies by API.'
            example: 1000
            type: integer
            format: int64
          offset:
            description: 'The 0-based offset of the first entry in this set. This will be the same

              as the `offset` query parameter.


              This field is only returned for calls that use offset-based pagination.

              For marker-based paginated APIs, this field will be omitted.'
            example: 2000
            type: integer
            format: int64
          order:
            description: 'The order by which items are returned.


              This field is only returned for calls that use offset-based pagination.

              For marker-based paginated APIs, this field will be omitted.'
            type: array
            items:
              type: object
              description: The order in which a pagination is ordered
              properties:
                by:
                  description: The field to order by
                  example: type
                  type: string
                direction:
                  type: string
                  description: The direction to order by, either ascending or descending
                  example: ASC
                  enum:
                  - ASC
                  - DESC
      - properties:
          entries:
            type: array
            description: A list of groups
            items:
              $ref: '#/components/schemas/Group--Full'
    ClientError:
      title: Client error
      type: object
      x-box-resource-id: client_error
      description: A generic error
      properties:
        type:
          description: error
          example: error
          type: string
          enum:
          - error
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
        code:
          description: A Box-specific error code
          example: item_name_invalid
          type: string
          enum:
          - created
          - accepted
          - no_content
          - redirect
          - not_modified
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - precondition_failed
          - too_many_requests
          - internal_server_error
          - unavailable
          - item_name_invalid
          - insufficient_scope
        message:
          description: A short message describing the error.
          example: Method Not Allowed
          type: string
        context_info:
          description: 'A free-form object that contains additional context

            about the error. The possible fields are defined on

            a per-endpoint basis. `message` is only one example.'
          type:
          - object
          - 'null'
          properties:
            message:
              type: string
              description: More details on the error.
              example: Something went wrong.
        help_url:
          description: A URL that links to more information about why this error occurred.
          example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
          type: string
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
    Group--Full:
      title: Group (Full)
      type: object
      x-box-resource-id: group--full
      x-box-variant: full
      description: 'Groups contain a set of users, and can be used in place of

        users in some operations, such as collaborations.'
      allOf:
      - $ref: '#/components/schemas/Group'
      - properties:
          provenance:
            type: string
            description: 'Keeps track of which external source this group is

              coming from (e.g. "Active Directory", "Google Groups",

              "Facebook Groups").  Setting this will

              also prevent Box users from editing the group name

              and its members directly via the Box web application.

              This is desirable for one-way syncing of groups.'
            maxLength: 255
            example: Active Directory
          external_sync_identifier:
            type: string
            description: 'An arbitrary identifier that can be used by

              external group sync tools to link this Box Group to

              an external group. Example values of this field

              could be an Active Directory Object ID or a Google

              Group ID.  We recommend you use of this field in

              order to avoid issues when group names are updated in

              either Box or external systems.'
            example: AD:123456
          description:
            type: string
            description: Human readable description of the group.
            maxLength: 255
            example: Support Group - as imported from Active Directory
          invitability_level:
            type: string
            example: admins_only
            description: 'Specifies who can invite the group to collaborate

              on items.


              When set to `admins_only` the enterprise admin, co-admins,

              and the group''s admin can invite the group.


              When set to `admins_and_members` all the admins listed

              above and group members can invite the group.


              When set to `all_managed_users` all managed users in the

              enterprise can invite the group.'
            enum:
            - admins_only
            - admins_and_members
            - all_managed_users
          member_viewability_level:
            type: string
            example: admins_only
            description: "Specifies who can view the members of the group\n(Get Memberships for Group).\n\n* `admins_only` - the enterprise admin, co-admins, group's\n  group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n  enterprise"
            enum:
            - admins_only
            - admins_and_members
            - all_managed_users
          permissions:
            allOf:
            - type: object
              description: The permissions that the authenticated user has for a group.
              properties:
                can_invite_as_collaborator:
                  type: boolean
                  description: Specifies if the user can invite the group to collaborate on any items.
                  example: true
            - description: 'Describes the permissions that the current user has

                for this group.'
    Group:
      title: Group
      type: object
      x-box-resource-id: group
      x-box-variant: standard
      description: 'A standard representation of a group, as returned from any

        group API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/Group--Mini'
      - properties:
          created_at:
            type: string
            format: date-time
            description: When the group object was created
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            description: When the group object was last modified
            example: '2012-12-12T10:53:43-08:00'
    Group--Base:
      title: Group (Base)
      type: object
      x-box-resource-id: group--base
      x-box-sanitized: true
      x-box-tag: groups
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: A base representation of a group.
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: The unique identifier for this object
          example: '11446498'
        type:
          type: string
          description: '`group`'
          example: group
          enum:
          - group
  securitySchemes:
    OAuth2Security:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.box.com/api/oauth2/authorize
          tokenUrl: https://api.box.com/oauth2/token
          scopes:
            root_readonly: Read all files and folders stored in Box
            root_readwrite: Read and write all files and folders stored in Box
            manage_app_users: Provision and manage app users
            manage_managed_users: Provision and manage managed users
            manage_groups: Manage an enterprise's groups
            manage_webhook: Create webhooks programmatically through the API
            manage_enterprise_properties: Manage enterprise properties
            manage_data_retention: Manage data retention polices
            manage_legal_hold: Manage Legal Holds
externalDocs:
  description: Box Developer Documentation
  url: https://developer.box.com