Box Integration Mappings API

openapi: 3.2.0
info:
  title: Box Integration Mappings API
  x-refined-note:
  - x-box-commit-hash differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Integration Mappings across 2 of this provider''s published API definitions: box-openapi-original.yml, integration-mappings-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
tags:
- name: Integration Mappings
  description: 'Integration Mappings allow the users

    to manage where content from partner apps is stored in Box.'
  x-box-tag: integration_mappings
paths:
  /integration_mappings/slack:
    get:
      operationId: get_integration_mappings_slack
      summary: Box List Slack integration mappings
      tags:
      - Integration Mappings
      x-box-tag: integration_mappings
      description: 'Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users'' enterprise.


        You need Admin or Co-Admin role to

        use this endpoint.'
      parameters:
      - name: marker
        description: 'Defines the position marker at which to begin returning results. This is

          used when paginating using marker-based pagination.


          This requires `usemarker` to be set to `true`.'
        in: query
        required: false
        example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
        schema:
          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
      - in: query
        name: partner_item_type
        schema:
          type: string
          enum:
          - channel
        description: Mapped item type, for which the mapping should be returned
        example: channel
      - in: query
        name: partner_item_id
        schema:
          type: string
        description: ID of the mapped item, for which the mapping should be returned
        example: '12345'
      - in: query
        name: box_item_id
        schema:
          type: string
        description: Box item ID, for which the mappings should be returned
        example: '12345'
      - in: query
        name: box_item_type
        schema:
          type: string
          enum:
          - folder
        description: Box item type, for which the mappings should be returned
        example: folder
      - in: query
        name: is_manually_created
        schema:
          type: boolean
        description: Whether the mapping has been manually created
        example: true
      responses:
        '200':
          description: Returns a collection of integration mappings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationMappings'
        '400':
          description: 'The server cannot or will not process the

            request due to an apparent client error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns a `not_found` error if the integration mapping could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
      security:
      - OAuth2Security: []
    post:
      operationId: post_integration_mappings_slack
      summary: Box Create Slack integration mapping
      tags:
      - Integration Mappings
      x-box-tag: integration_mappings
      description: 'Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack)

        by mapping a Slack channel to a Box item.


        You need Admin or Co-Admin role to

        use this endpoint.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationMappingSlackCreateRequest'
      responses:
        '201':
          description: Returns the created integration mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationMapping'
        '400':
          description: "Returns a `bad_request` if an incorrect `options`\nwas supplied or the Box folder cannot be\nmapped to this `partner_item_id`.\nError codes:\n* `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account\ndoesn't have co-owner collaboration or is\nnot an owner of the `box_item_id`,\n* `CHANNEL_ALREADY_MAPPED` - channel is already\n  mapped to another `box_item_id`,\n* `CHANNEL_NOT_FOUND` - channel was not found,\n* `CHANNEL_NOT_SUITABLE_FOR_CFS` - connect channel, not\nsuitable for Box as Content layer for Slack,\n* `BOX_ENTERPRISE_MISMATCH` - Box folder must be\nowned by the enterprise, which is configured\nto use Box as Content layer for Slack,\n* `CFS_DISABLED` - Box as Content layer\nfor Slack must be enabled for a provided\nSlack workspace or organization\n* `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must\nbe internally owned to the admin's enterprise,\n* `JWT_APP_NOT_AUTHORIZED` - JWT authorization error."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns a `not_found` error if the integration mapping could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
      security:
      - OAuth2Security: []
    servers:
    - url: https://api.box.com/2.0
      description: Box Platform API server
  /integration_mappings/slack/{integration_mapping_id}:
    put:
      operationId: put_integration_mappings_slack_id
      summary: Box Update Slack integration mapping
      tags:
      - Integration Mappings
      x-box-tag: integration_mappings
      description: 'Updates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack).

        Supports updating the Box folder ID and options.


        You need Admin or Co-Admin role to

        use this endpoint.'
      parameters:
      - name: integration_mapping_id
        description: An ID of an integration mapping
        example: '11235432'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                box_item:
                  allOf:
                  - $ref: '#/components/schemas/IntegrationMappingBoxItemSlack'
                options:
                  allOf:
                  - $ref: '#/components/schemas/IntegrationMappingSlackOptions'
        description: At least one of `box_item` and `options` must be provided.
      responses:
        '200':
          description: Returns the updated integration mapping object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationMapping'
        '400':
          description: "Returns a `bad_request` if an incorrect `options` was\nsupplied or the Box folder cannot be mapped to this `partner_item`.\nError codes:\n* `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account\n  doesn't have co-owner collaboration or is\n  not an owner of the `box_item_id`,\n* `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be\n  internally owned to the admin's enterprise,\n* `JWT_APP_NOT_AUTHORIZED` - JWT authorization error."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns `not_found` if integration mapping object was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
      security:
      - OAuth2Security: []
    delete:
      operationId: delete_integration_mappings_slack_id
      summary: Box Delete Slack integration mapping
      tags:
      - Integration Mappings
      x-box-tag: integration_mappings
      description: 'Deletes a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack).



        You need Admin or Co-Admin role to

        use this endpoint.'
      parameters:
      - name: integration_mapping_id
        description: An ID of an integration mapping
        example: '11235432'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Empty body in response
        '404':
          description: Returns a `not_found` error if the integration mapping could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
      security:
      - OAuth2Security: []
    servers:
    - url: https://api.box.com/2.0
      description: Box Platform API server
components:
  schemas:
    IntegrationMappingBoxItemSlack:
      title: Integration mapping Box item schema for type Slack
      type: object
      description: The schema for an integration mapping Box item object for type Slack
      properties:
        type:
          type: string
          enum:
          - folder
          example: folder
          description: Type of the mapped item referenced in `id`
        id:
          type: string
          example: '1234567891'
          description: ID of the mapped item (of type referenced in `type`)
      required:
      - id
      - type
    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
    IntegrationMappingSlackOptions:
      title: Integration mapping options for type Slack
      type: object
      description: The schema for an integration mapping options object for Slack type.
      properties:
        is_access_management_disabled:
          type: boolean
          example: true
          description: 'Indicates whether or not channel member

            access to the underlying box item

            should be automatically managed.

            Depending on type of channel, access is managed

            through creating collaborations or shared links.'
    IntegrationMapping:
      title: Integration mapping
      type: object
      x-box-resource-id: integration_mapping
      x-box-tag: integration_mappings
      x-box-variant: standard
      description: 'A standard representation of an integration

        mapping object.'
      allOf:
      - $ref: '#/components/schemas/IntegrationMapping--Base'
      - properties:
          type:
            type: string
            example: integration_mapping
            enum:
            - integration_mapping
            description: Mapping type
          partner_item:
            oneOf:
            - $ref: '#/components/schemas/IntegrationMappingPartnerItemSlack'
            description: Mapped item object for Slack
          box_item:
            allOf:
            - $ref: '#/components/schemas/Folder--Mini'
            description: 'The Box folder, to which the object from the

              partner app domain (referenced in `partner_item_id`) is mapped'
          is_manually_created:
            type: boolean
            example: true
            description: 'Identifies whether the mapping has

              been manually set

              (as opposed to being automatically created)'
          options:
            type: object
            example: {}
            description: Integration mapping options for Slack
            anyOf:
            - $ref: '#/components/schemas/IntegrationMappingSlackOptions'
          created_by:
            allOf:
            - $ref: '#/components/schemas/UserIntegrationMappings'
            description: 'An object representing the user who

              created the integration mapping'
          modified_by:
            allOf:
            - $ref: '#/components/schemas/UserIntegrationMappings'
            description: 'The user who

              last modified the integration mapping'
          created_at:
            type: string
            format: date-time
            description: When the integration mapping object was created
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            description: When the integration mapping object was last modified
            example: '2012-12-12T10:53:43-08:00'
      required:
      - type
      - partner_item
      - box_item
    Folder--Mini:
      title: Folder (Mini)
      type: object
      x-box-resource-id: folder--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested under another resource.'
      allOf:
      - $ref: '#/components/schemas/Folder--Base'
      - properties:
          sequence_id:
            allOf:
            - type:
              - string
              - 'null'
              example: '3'
              description: 'A numeric identifier that represents the most recent user event

                that has been applied to this item.


                This can be used in combination with the `GET /events`-endpoint

                to filter out user events that would have occurred before this

                identifier was read.


                An example would be where a Box Drive-like application

                would fetch an item via the API, and then listen to incoming

                user events for changes to the item. The application would

                ignore any user events where the `sequence_id` in the event

                is smaller than or equal to the `sequence_id` in the originally

                fetched resource.'
            - {}
          name:
            type: string
            description: The name of the folder.
            example: Contracts
    IntegrationMappings:
      title: Integration mappings
      type: object
      x-box-resource-id: integration_mappings
      x-box-tag: integration_mappings
      description: 'A list of integration mapping

        objects.'
      allOf:
      - type: object
        description: 'The part of an API response that describes marker

          based pagination'
        properties:
          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
          next_marker:
            description: The marker for the start of the next page of results.
            example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
            type:
            - string
            - 'null'
      - properties:
          entries:
            type: array
            description: A list of integration mappings
            items:
              $ref: '#/components/schemas/IntegrationMapping'
    IntegrationMappingPartnerItemSlack:
      title: Integration mapping mapped item schema for type Slack
      type: object
      description: 'The schema for an integration mapping mapped item object for type Slack.


        Depending if Box for Slack is installed at the org or workspace level,

        provide **either** `slack_org_id` **or** `slack_workspace_id`.

        Do not use both parameters at the same time.'
      properties:
        type:
          type: string
          enum:
          - channel
          example: channel
          description: Type of the mapped item referenced in `id`
        id:
          type: string
          example: C12378991223
          description: ID of the mapped item (of type referenced in `type`)
        slack_workspace_id:
          type:
          - string
          - 'null'
          example: T12352314
          description: ID of the Slack workspace with which the item is associated. Use this parameter if Box for Slack is installed at a workspace level. Do not use `slack_org_id` at the same time.
        slack_org_id:
          type:
          - string
          - 'null'
          example: E1234567
          description: ID of the Slack org with which the item is associated. Use this parameter if Box for Slack is installed at the org level. Do not use `slack_workspace_id` at the same time.
      required:
      - id
      - type
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          enum:
          - user
    UserIntegrationMappings:
      title: User (Integration Mappings)
      type: object
      x-box-resource-id: user_integration_mappings_reference
      x-box-tag: users
      description: 'A user representation for integration mappings

        API purposes. Fields name and login are not required.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
    IntegrationMapping--Base:
      title: Integration mapping (Base)
      type: object
      x-box-resource-id: integration_mapping--base
      x-box-tag: integration_mappings
      x-box-variant: base
      x-box-variants:
      - base
      - standard
      - mini
      description: 'A base representation of an

        integration mapping object.'
      properties:
        id:
          type: string
          example: '12345'
          description: 'A unique identifier of a folder mapping

            (part of a composite key together

            with `integration_type`)'
        integration_type:
          type: string
          description: 'Identifies the Box partner app,

            with which the mapping is associated.

            Currently only supports Slack.

            (part of the composite key together with `id`)'
          example: slack
          enum:
          - slack
    Folder--Base:
      title: Folder (Base)
      type: object
      x-box-resource-id: folder--base
      x-box-sanitized: true
      x-box-tag: folders
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a folder, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: 'The unique identifier that represent a folder.


            The ID for any folder can be determined

            by visiting a folder in the web application

            and copying the ID from the URL. For example,

            for the URL `https://*.app.box.com/folders/123`

            the `folder_id` is `123`.'
          example: '12345'
        etag:
          type:
          - string
          - 'null'
          example: '1'
          description: 'The HTTP `etag` of this folder. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the folder if (no) changes have happened.'
        type:
          type: string
          description: '`folder`'
          example: folder
          enum:
          - folder
    IntegrationMappingSlackCreateRequest:
      title: Create integration mapping request
      type: object
      x-box-resource-id: integration_mapping_slack_create_request
      description: 'A request to create a

        Slack Integration Mapping object'
      properties:
        partner_item:
          allOf:
          - $ref: '#/components/schemas/IntegrationMappingPartnerItemSlack'
        box_item:
          allOf:
          - $ref: '#/components/schemas/IntegrationMappingBoxItemSlack'
        options:
          allOf:
          - $ref: '#/components/schemas/IntegrationMappingSlackOptions'
      required:
      - partner_item
      - box_item
    ClientError_2:
      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
          nullable: false
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
          nullable: false
        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
          nullable: false
        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
          nullable: true
          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
          nullable: false
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
          nullable: false
    IntegrationMapping_2:
      title: Integration mapping
      type: object
      x-box-resource-id: integration_mapping
      x-box-tag: integration_mappings
      x-box-variant: standard
      description: 'A standard representation of an integration

        mapping object.'
      allOf:
      - $ref: '#/components/schemas/IntegrationMapping--Base'
      - properties:
          type:
            type: string
            example: integration_mapping
            enum:
            - integration_mapping
            description: Mapping type
            nullable: false
          partner_item:
            oneOf:
            - $ref: '#/components/schemas/IntegrationMappingPartnerItemSlack'
            nullable: false
            description: Mapped item object for Slack
          box_item:
            allOf:
            - $ref: '#/components/schemas/Folder--Mini'
            description: 'The Box folder, to which the object from the

              partner app domain (referenced in `partner_item_id`) is mapped'
            nullable: false
          is_manually_created:
            type: boolean
            example: true
            description: 'Identifies whether the mapping has

              been manually set

              (as opposed to being automatically created)'
            nullable: false
          options:
            type: object
            nullable: false
            example: {}
            description: Integration mapping options for Slack
            anyOf:
            - $ref: '#/components/schemas/IntegrationMappingSlackOptions'
          created_by:
            allOf:
            - $ref: '#/components/schemas/UserIntegrationMappings'
            description: 'An object representing the user who

              created the integration mapping'
            nullable: false
          modified_by:
            allOf:
            - $ref: '#/components/schemas/UserIntegrationMappings'
            description: 'The user who

              last modified the integration mapping'
            nullable: false
          created_at:
            type: string
            format: date-time
            description: When the integration mapping object was created
            example: '2012-12-12T10:53:43-08:00'
            nullable: false
          modified_at:
            type: string
            format: date-time
            description: When the integration mapping object was last modified
            example: '2012-12-12T10:53:43-08:00'
            nullable: false
      required:
      - type
      - partner_item
      - box_item
    IntegrationMappings_2:
      title: Integration mappings
      type: object
      x-box-resource-id: integration_mappings
      x-box-tag: integration_mappings
      description: 'A list of integration mapping

        objects.'
      allOf:
      - type: object
        description: 'The part of an API response that describes marker

          based pagination'
        properties:
          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
          next_marker:
            description: The marker for the start of the next page of results.
            example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
            type: string
            nullable: true
      - properties:
          entries:
            type: array
            description: A list of integration mappings
            items:
              $ref: '#/components/schemas/IntegrationMapping_2'
  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
x-refined-from:
- box-openapi-original.yml
- integration-mappings-openapi-original.yml