Box
Box Legal Hold Policy Assignments API

A Legal Hold Policy Assignment is a relation between a policy and custodian. In this case, as custodian can be a user, folder, file, or file version.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Legal Hold Policy Assignments API
  description: Needs a description.
tags:
- name: Legal Hold Policy Assignments
  description: 'A Legal Hold Policy Assignment

    is a relation between a policy and custodian.

    In this case, as custodian can be a user, folder,

    file, or file version.'
  x-box-tag: legal_hold_policy_assignments
paths:
  /legal_hold_policy_assignments:
    get:
      operationId: get_legal_hold_policy_assignments
      summary: Box List legal hold policy assignments
      tags:
      - Legal Hold Policy Assignments
      x-box-tag: legal_hold_policy_assignments
      description: Retrieves a list of items a legal hold policy has been assigned to.
      parameters:
      - name: policy_id
        description: The ID of the legal hold policy
        example: '324432'
        in: query
        required: true
        schema:
          type: string
      - name: assign_to_type
        description: 'Filters the results by the type of item the

          policy was applied to.'
        example: file
        in: query
        schema:
          type: string
          enum:
          - file
          - file_version
          - folder
          - user
      - name: assign_to_id
        description: 'Filters the results by the ID of item the

          policy was applied to.'
        example: '1234323'
        in: query
        schema:
          type: string
      - 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
      - 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 a list of legal hold policy assignments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalHoldPolicyAssignments'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    post:
      operationId: post_legal_hold_policy_assignments
      summary: Box Assign legal hold policy
      tags:
      - Legal Hold Policy Assignments
      x-box-tag: legal_hold_policy_assignments
      description: Assign a legal hold to a file, file version, folder, or user.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - policy_id
              - assign_to
              properties:
                policy_id:
                  description: The ID of the policy to assign.
                  example: '123244'
                  type: string
                assign_to:
                  type: object
                  description: The item to assign the policy to
                  required:
                  - type
                  - id
                  properties:
                    type:
                      type: string
                      description: The type of item to assign the policy to
                      example: folder
                      enum:
                      - file
                      - file_version
                      - folder
                      - user
                    id:
                      type: string
                      description: The ID of item to assign the policy to
                      example: '6564564'
      responses:
        '201':
          description: Returns a new legal hold policy assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalHoldPolicyAssignment'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}:
    get:
      operationId: get_legal_hold_policy_assignments_id
      summary: Box Get legal hold policy assignment
      tags:
      - Legal Hold Policy Assignments
      x-box-tag: legal_hold_policy_assignments
      description: Retrieve a legal hold policy assignment.
      parameters:
      - name: legal_hold_policy_assignment_id
        description: The ID of the legal hold policy assignment
        example: '753465'
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a legal hold policy object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalHoldPolicyAssignment'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_legal_hold_policy_assignments_id
      x-box-tag: legal_hold_policy_assignments
      tags:
      - Legal Hold Policy Assignments
      summary: Box Unassign legal hold policy
      description: 'Remove a legal hold from an item.


        This is an asynchronous process. The policy will not be

        fully removed yet when the response returns.'
      parameters:
      - name: legal_hold_policy_assignment_id
        description: The ID of the legal hold policy assignment
        example: '753465'
        in: path
        required: true
        schema:
          type: string
      responses:
        '202':
          description: 'A blank response is returned if the assignment was

            successfully deleted.'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold:
    get:
      operationId: get_legal_hold_policy_assignments_id_files_on_hold
      summary: Box List current file versions for legal hold policy assignment
      tags:
      - Legal Hold Policy Assignments
      x-box-tag: legal_hold_policy_assignments
      description: 'Get a list of current file versions for a legal hold

        assignment.


        In some cases you may want to get previous file versions instead. In these

        cases, use the `GET  /legal_hold_policy_assignments/:id/file_versions_on_hold`

        API instead to return any previous versions of a file for this legal hold

        policy assignment.


        Due to ongoing re-architecture efforts this API might not return all file

        versions held for this policy ID. Instead, this API will only return the

        latest file version held in the newly developed architecture. The `GET

        /file_version_legal_holds` API can be used to fetch current and past versions

        of files held within the legacy architecture.


        The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to

        find a list of policy assignments for a given policy ID.'
      parameters:
      - name: legal_hold_policy_assignment_id
        description: The ID of the legal hold policy assignment
        example: '753465'
        in: path
        required: true
        schema:
          type: string
      - 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
      - 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 list of current file versions held under legal hold for a

            specific legal hold policy assignment.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersionLegalHolds'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold:
    get:
      operationId: get_legal_hold_policy_assignments_id_file_versions_on_hold
      summary: Box List previous file versions for legal hold policy assignment
      tags:
      - Legal Hold Policy Assignments
      x-box-tag: legal_hold_policy_assignments
      description: 'Get a list of previous file versions for a legal hold

        assignment.


        In some cases you may only need the latest file versions instead. In these

        cases, use the `GET  /legal_hold_policy_assignments/:id/files_on_hold` API

        instead to return any current (latest) versions of a file for this legal hold

        policy assignment.


        Due to ongoing re-architecture efforts this API might not return all files

        held for this policy ID. Instead, this API will only return past file versions

        held in the newly developed architecture. The `GET /file_version_legal_holds`

        API can be used to fetch current and past versions of files held within the

        legacy architecture.


        The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to

        find a list of policy assignments for a given policy ID.'
      parameters:
      - name: legal_hold_policy_assignment_id
        description: The ID of the legal hold policy assignment
        example: '753465'
        in: path
        required: true
        schema:
          type: string
      - 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
      - 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 list of previous file versions held under legal hold for a

            specific legal hold policy assignment.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileVersionLegalHolds'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    Folder:
      title: Folder
      type: object
      x-box-resource-id: folder
      x-box-variant: standard
      description: 'A standard representation of a folder, as returned from any

        folder API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/Folder--Mini'
      - properties:
          created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time when the folder was created. This value may

              be `null` for some folders such as the root folder or the trash

              folder.'
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            description: 'The date and time when the folder was last updated. This value may

              be `null` for some folders such as the root folder or the trash

              folder.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          description:
            allOf:
            - type: string
              description: The optional description of this folder
              maxLength: 256
              example: Legal contracts for the new ACME deal
              nullable: false
            - nullable: false
          size:
            type: integer
            format: int64
            description: 'The folder size in bytes.


              Be careful parsing this integer as its

              value can get very large.'
            example: 629644
            nullable: false
          path_collection:
            allOf:
            - title: Path collection
              description: A list of parent folders for an item.
              type: object
              required:
              - total_count
              - entries
              properties:
                total_count:
                  description: The number of folders in this list.
                  example: 1
                  type: integer
                  format: int64
                  nullable: false
                entries:
                  type: array
                  description: The parent folders for this item
                  nullable: false
                  items:
                    $ref: '#/components/schemas/Folder--Mini'
            - description: 'The tree of folders that this folder is contained in,

                starting at the root.'
            - nullable: false
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this folder
            - nullable: false
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this folder.
            - nullable: false
          trashed_at:
            type: string
            format: date-time
            description: The time at which this folder was put in the trash.
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          purged_at:
            type: string
            format: date-time
            description: 'The time at which this folder is expected to be purged

              from the trash.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          content_created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this folder was originally

              created.'
            example: '2012-12-12T10:53:43-08:00'
          content_modified_at:
            type: string
            format: date-time
            nullable: true
            description: The date and time at which this folder was last updated.
            example: '2012-12-12T10:53:43-08:00'
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this folder.
            - nullable: false
          shared_link:
            allOf:
            - title: Shared link
              description: 'Shared links provide direct, read-only access to files or folder on Box.


                Shared links with open access level allow anyone with the URL

                to access the item, while shared links with company or collaborators access

                levels can only be accessed by appropriately authenticated Box users.'
              type: object
              required:
              - url
              - accessed
              - effective_access
              - effective_permission
              - is_password_enabled
              - download_count
              - preview_count
              properties:
                url:
                  type: string
                  format: url
                  description: 'The URL that can be used to access the item on Box.


                    This URL will display the item in Box''s preview UI where the file

                    can be downloaded if allowed.


                    This URL will continue to work even when a custom `vanity_url`

                    has been set for this shared link.'
                  example: https://www.box.com/s/vspke7y05sb214wjokpk
                  nullable: false
                download_url:
                  type: string
                  format: url
                  x-box-premium-feature: true
                  description: 'A URL that can be used to download the file. This URL can be used in

                    a browser to download the file. This URL includes the file

                    extension so that the file will be saved with the right file type.


                    This property will be `null` for folders.'
                  example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
                  nullable: true
                vanity_url:
                  type: string
                  format: url
                  description: 'The "Custom URL" that can also be used to preview the item on Box.  Custom

                    URLs can only be created or modified in the Box Web application.'
                  example: https://acme.app.box.com/v/my_url/
                  nullable: true
                vanity_name:
                  type: string
                  description: The custom name of a shared link, as used in the `vanity_url` field.
                  example: my_url
                  nullable: true
                access:
                  type: string
                  description: "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n   collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin."
                  enum:
                  - open
                  - company
                  - collaborators
                  example: open
                  nullable: false
                effective_access:
                  type: string
                  description: 'The effective access level for the shared link. This can be a more

                    restrictive access level than the value in the `access` field when the

                    enterprise settings restrict the allowed access levels.'
                  enum:
                  - open
                  - company
                  - collaborators
                  example: company
                  nullable: false
                effective_permission:
                  type: string
                  description: 'The effective permissions for this shared link.

                    These result in the more restrictive combination of

                    the share link permissions and the item permissions set

                    by the administrator, the owner, and any ancestor item

                    such as a folder.'
                  enum:
                  - can_edit
                  - can_download
                  - can_preview
                  - no_access
                  example: can_download
                  nullable: false
                unshared_at:
                  type: string
                  format: date-time
                  description: 'The date and time when this link will be unshared. This field can only be

                    set by users with paid accounts.'
                  example: '2018-04-13T13:53:23-07:00'
                  nullable: true
                is_password_enabled:
                  type: boolean
                  description: Defines if the shared link requires a password to access the item.
                  example: true
                  nullable: false
                permissions:
                  type: object
                  description: 'Defines if this link allows a user to preview, edit, and download an item.

                    These permissions refer to the shared link only and

                    do not supersede permissions applied to the item itself.'
                  required:
                  - can_download
                  - can_preview
                  - can_edit
                  properties:
                    can_download:
                      type: boolean
                      example: true
                      nullable: false
                      description: 'Defines if the shared link allows for the item to be downloaded. For

                        shared links on folders, this also applies to any items in the folder.


                        This value can be set to `true` when the effective access level is

                        set to `open` or `company`, not `collaborators`.'
                    can_preview:
                      type: boolean
                      example: true
                      nullable: false
                      description: 'Defines if the shared link allows for the item to be previewed.


                        This value is always `true`. For shared links on folders this also

                        applies to any items in the folder.'
                    can_edit:
                      type: boolean
                      example: false
                      nullable: false
                      description: 'Defines if the shared link allows for the item to be edited.


                        This value can only be `true` if `can_download` is also `true` and if

                        the item has a type of `file`.'
                download_count:
                  type: integer
                  example: 3
                  description: The number of times this item has been downloaded.
                  nullable: false
                preview_count:
                  type: integer
                  example: 3
                  description: The number of times this item has been previewed.
                  nullable: false
            - description: 'The shared link for this folder. This will be

                `null` if no shared link has been created for this

                folder.'
            nullable: true
          folder_upload_email:
            type: object
            nullable: true
            properties:
              access:
                type: string
                example: open
                nullable: false
                enum:
                - open
                - collaborators
                description: 'When this parameter has been set, users can email files

                  to the email address that has been automatically

                  created for this folder.


                  To create an email address, set this property either when

                  creating or updating the folder.


                  When set to `collaborators`, only emails from registered email

                  addresses for collaborators will be accepted. This includes

                  any email aliases a user might have registered.


                  When set to `open` it will accept emails from any email

                  address.'
              email:
                description: The optional upload email address for this folder.
                type: string
                format: email
                example: upload.Contracts.asd7asd@u.box.com
                nullable: false
          parent:
            allOf:
            - $ref: '#/components/schemas/Folder--Mini'
            - description: 'The optional folder that this folder is located within.


                This value may be `null` for some folders such as the

                root folder or the trash folder.'
            nullable: true
          item_status:
            type: string
            description: 'Defines if this item has been deleted or not.


              * `active` when the item has is not in the trash

              * `trashed` when the item has been moved to the trash but not deleted

              * `deleted` when the item has been permanently deleted.'
            enum:
            - active
            - trashed
            - deleted
            nullable: false
            example: active
          item_collection:
            allOf:
            - $ref: '#/components/schemas/Items'
            - description: 'A page of the items that are in the folder.


                This field can only be requested when querying a folder''s

                information, not when querying a folder''s items.'
            - nullable: false
    File:
      title: File
      type: object
      x-box-resource-id: file
      x-box-variant: standard
      description: 'A standard representation of a file, as returned from any

        file API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/File--Mini'
      - properties:
          description:
            type: string
            nullable: false
            description: The optional description of this file
            maxLength: 256
            example: Contract for Q1 renewal
          size:
            type: integer
            nullable: false
            description: 'The file size in bytes. Be careful parsing this integer as it can

              get very large and cause an integer overflow.'
            example: 629644
          path_collection:
            allOf:
            - title: Path collection
              description: A list of parent folders for an item.
              type: object
              required:
              - total_count
              - entries
              properties:
                total_count:
                  description: The number of folders in this list.
                  example: 1
                  type: integer
                  format: int64
                  nullable: false
                entries:
                  type: array
                  description: The parent folders for this item
                  nullable: false
                  items:
                    $ref: '#/components/schemas/Folder--Mini'
            - description: 'The tree of folders that this file is contained in,

                starting at the root.'
            - nullable: false
          created_at:
            type: string
            format: date-time
            nullable: false
            description: The date and time when the file was created on Box.
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            nullable: false
            description: The date and time when the file was last updated on Box.
            example: '2012-12-12T10:53:43-08:00'
          trashed_at:
            type: string
            format: date-time
            description: The time at which this file was put in the trash.
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          purged_at:
            type: string
            format: date-time
            description: 'The time at which this file is expected to be purged

              from the trash.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          content_created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this file was originally

              created, which might be before it was uploaded to Box.'
            example: '2012-12-12T10:53:43-08:00'
          content_modified_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this file was last updated,

              which might be before it was uploaded to Box.'
            example: '2012-12-12T10:53:43-08:00'
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this file
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this file
            - nullable: false
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this file
            - nullable: false
          shared_link:
            allOf:
            - title: Shared link
              description: 'Shared links provide direct, read-only access to files or folder on Box.


                Shared links with open access level allow anyone with the URL

                to access the item, while shared links with company or collaborators access

                levels can only be accessed by appropriately authenticated Box users.'
              type: object
              required:
              - url
              - accessed
              - effective_access
              - effective_permission
              - is_password_enabled
              - download_count
              - preview_count
              properties:
                url:
                  type: string
                  format: url
                  description: 'The URL that can be used to access the item on Box.


                    This URL will display the item in Box''s preview UI where the file

                    can be downloaded if allowed.


                    This URL will continue to work even when a custom `vanity_url`

                    has been set for this shared link.'
                  example: https://www.box.com/s/vspke7y05sb214wjokpk
                  nullable: false
                download_url:
                  type: string
                  format: url
                  x-box-premium-feature: true
                  description: 'A URL that can be used to download the file. This URL can be used in

      

# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-legal-hold-policy-assignments-api-openapi.yml
Box Legal Hold Policy Assignments API

Documentation

Specifications

Other Resources

OpenAPI Specification
