Box

Box Legal Hold Policies API

A legal hold is a process that an enterprise can use to preserve all forms of potentially relevant information when litigation is pending or reasonably anticipated.

Documentation GitHub OpenAPI

Documentation

https://developer.box.com/reference/get-authorize

https://developer.box.com/reference/post-oauth2-token

https://developer.box.com/reference/post-files-id-copy

https://developer.box.com/reference/post-file-requests-id-copy

https://developer.box.com/reference/post-folders-id-copy

https://developer.box.com/reference/post-folder-locks

https://developer.box.com/reference/post-metadata-templates-schema

https://developer.box.com/reference/post-metadata-cascade-policies

https://developer.box.com/reference/post-metadata-queries-execute-read

https://developer.box.com/reference/post-comments

https://developer.box.com/reference/post-collaborations

https://developer.box.com/reference/post-tasks

https://developer.box.com/reference/post-task-assignments

https://developer.box.com/reference/put-files-id--add-shared-link

https://developer.box.com/reference/put-folders-id--add-shared-link

https://developer.box.com/reference/post-web-links

https://developer.box.com/reference/put-web-links-id--add-shared-link

https://developer.box.com/reference/post-users

https://developer.box.com/reference/post-invites

https://developer.box.com/reference/post-groups

https://developer.box.com/reference/post-group-memberships

https://developer.box.com/reference/post-webhooks

https://developer.box.com/reference/post-files-id-metadata-global-boxSkillsCards

https://developer.box.com/reference/options-events

https://developer.box.com/reference/get-collections-id

https://developer.box.com/reference/get-recent-items

https://developer.box.com/reference/post-retention-policies

https://developer.box.com/reference/post-retention-policy-assignments

https://developer.box.com/reference/post-legal-hold-policies

https://developer.box.com/reference/post-legal-hold-policy-assignments

https://developer.box.com/reference/get-file-version-retentions-id

https://developer.box.com/reference/get-file-version-legal-holds-id

https://developer.box.com/reference/post-shield-information-barriers-change-status

https://developer.box.com/reference/post-shield-information-barrier-reports

https://developer.box.com/reference/post-shield-information-barrier-segments

https://developer.box.com/reference/post-shield-information-barrier-segment-members

https://developer.box.com/reference/post-shield-information-barrier-segment-restrictions

https://developer.box.com/reference/get-device-pinners-id

https://developer.box.com/reference/post-terms-of-services

https://developer.box.com/reference/post-terms-of-service-user-statuses

https://developer.box.com/reference/post-collaboration-whitelist-entries

https://developer.box.com/

Specifications

https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-legal-hold-policies-api-openapi.yml

Other Resources

https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/graphql/box-graphql.md

OpenAPI Specification

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Legal Hold Policies API
  description: Needs a description.
tags:
- name: Legal Hold Policies
  description: 'A legal hold is a process that an enterprise

    can use to preserve all forms of potentially

    relevant information when litigation is pending or

    reasonably anticipated.'
  x-box-tag: legal_hold_policies
paths:
  /legal_hold_policies:
    get:
      operationId: get_legal_hold_policies
      summary: Box List all legal hold policies
      tags:
      - Legal Hold Policies
      x-box-tag: legal_hold_policies
      description: 'Retrieves a list of legal hold policies that belong to

        an enterprise.'
      parameters:
      - name: policy_name
        description: 'Limits results to policies for which the names start with

          this search term. This is a case-insensitive prefix.'
        in: query
        example: Sales Policy
        required: false
        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: 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
      responses:
        '200':
          description: Returns a list of legal hold policies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalHoldPolicies'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    post:
      operationId: post_legal_hold_policies
      summary: Box Create legal hold policy
      tags:
      - Legal Hold Policies
      x-box-tag: legal_hold_policies
      description: Create a new legal hold policy.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - policy_name
              properties:
                policy_name:
                  description: The name of the policy.
                  example: Sales Policy
                  type: string
                  maxLength: 254
                description:
                  description: A description for the policy.
                  example: A custom policy for the sales team
                  type: string
                  maxLength: 500
                filter_started_at:
                  description: 'The filter start date.


                    When this policy is applied using a `custodian` legal

                    hold assignments, it will only apply to file versions

                    created or uploaded inside of the

                    date range. Other assignment types, such as folders and

                    files, will ignore the date filter.


                    Required if `is_ongoing` is set to `false`.'
                  example: '2012-12-12T10:53:43-08:00'
                  type: string
                  maxLength: 500
                  format: date-time
                filter_ended_at:
                  description: 'The filter end date.


                    When this policy is applied using a `custodian` legal

                    hold assignments, it will only apply to file versions

                    created or uploaded inside of the

                    date range. Other assignment types, such as folders and

                    files, will ignore the date filter.


                    Required if `is_ongoing` is set to `false`.'
                  example: '2012-12-18T10:53:43-08:00'
                  type: string
                  maxLength: 500
                  format: date-time
                is_ongoing:
                  description: 'Whether new assignments under this policy should

                    continue applying to files even after initialization.


                    When this policy is applied using a legal hold assignment,

                    it will continue applying the policy to any new file versions

                    even after it has been applied.


                    For example, if a legal hold assignment is placed on a user

                    today, and that user uploads a file tomorrow, that file will

                    get held. This will continue until the policy is retired.


                    Required if no filter dates are set.'
                  example: true
                  type: boolean
      responses:
        '201':
          description: Returns a new legal hold policy object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalHoldPolicy'
        '400':
          description: 'Returns an error if required parameters are missing,

            or neither `is_ongoing` or filter dates are specified.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: Returns an error if a policy with this name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /legal_hold_policies/{legal_hold_policy_id}:
    get:
      operationId: get_legal_hold_policies_id
      summary: Box Get legal hold policy
      tags:
      - Legal Hold Policies
      x-box-tag: legal_hold_policies
      description: Retrieve a legal hold policy.
      parameters:
      - name: legal_hold_policy_id
        description: The ID of the legal hold policy
        example: '324432'
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a legal hold policy object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalHoldPolicy'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_legal_hold_policies_id
      summary: Box Update legal hold policy
      tags:
      - Legal Hold Policies
      x-box-tag: legal_hold_policies
      description: Update legal hold policy.
      parameters:
      - name: legal_hold_policy_id
        description: The ID of the legal hold policy
        example: '324432'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                policy_name:
                  description: The name of the policy.
                  example: Sales Policy
                  type: string
                  maxLength: 254
                description:
                  description: A description for the policy.
                  example: A custom policy for the sales team
                  type: string
                  maxLength: 500
                release_notes:
                  description: Notes around why the policy was released.
                  example: Required for GDPR
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: Returns a new legal hold policy object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalHoldPolicy'
        '409':
          description: Returns an error if a policy with this name already exists.
          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_legal_hold_policies_id
      x-box-tag: legal_hold_policies
      tags:
      - Legal Hold Policies
      summary: Box Remove legal hold policy
      description: 'Delete an existing legal hold policy.


        This is an asynchronous process. The policy will not be

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

            successfully deleted.'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    LegalHoldPolicy:
      title: Legal hold policy
      type: object
      x-box-resource-id: legal_hold_policy
      x-box-variant: standard
      description: 'Legal Hold Policy information describes the basic

        characteristics of the Policy, such as name, description,

        and filter dates.'
      allOf:
      - $ref: '#/components/schemas/LegalHoldPolicy--Mini'
      - properties:
          policy_name:
            type: string
            example: Policy 4
            description: Name of the legal hold policy.
            maxLength: 254
          description:
            type: string
            description: 'Description of the legal hold policy. Optional

              property with a 500 character limit.'
            maxLength: 500
            example: Postman created policy
          status:
            type: string
            example: active
            enum:
            - active
            - applying
            - releasing
            - released
            description: "* 'active' - the policy is not in a transition state\n* 'applying' - that the policy is in the process of\n  being applied\n* 'releasing' - that the process is in the process\n  of being released\n* 'released' - the policy is no longer active"
          assignment_counts:
            type: object
            description: Counts of assignments within this a legal hold policy by item type
            properties:
              user:
                type: integer
                format: int64
                description: The number of users this policy is applied to
                example: 1
              folder:
                type: integer
                format: int64
                description: The number of folders this policy is applied to
                example: 2
              file:
                type: integer
                format: int64
                description: The number of files this policy is applied to
                example: 3
              file_version:
                type: integer
                format: int64
                description: The number of file versions this policy is applied to
                example: 4
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created the legal hold policy object
          created_at:
            type: string
            format: date-time
            description: When the legal hold policy object was created
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            description: 'When the legal hold policy object was modified.

              Does not update when assignments are added or removed.'
            example: '2012-12-12T10:53:43-08:00'
          deleted_at:
            type: string
            format: date-time
            description: 'When the policy release request was sent. (Because

              it can take time for a policy to fully delete, this

              isn''t quite the same time that the policy is fully deleted).


              If `null`, the policy was not deleted.'
            example: '2012-12-12T10:53:43-08:00'
          filter_started_at:
            type: string
            format: date-time
            description: 'User-specified, optional date filter applies to

              Custodian assignments only'
            example: '2012-12-12T10:53:43-08:00'
          filter_ended_at:
            type: string
            format: date-time
            description: 'User-specified, optional date filter applies to

              Custodian assignments only'
            example: '2012-12-12T10:53:43-08:00'
          release_notes:
            type: string
            example: Example
            description: Optional notes about why the policy was created.
            maxLength: 500
    LegalHoldPolicies:
      title: Legal hold policies
      type: object
      x-box-resource-id: legal_hold_policies
      x-box-tag: legal_hold_policies
      description: A list of legal hold policies.
      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
          prev_marker:
            description: The marker for the start of the previous page of results.
            example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
            type: string
            nullable: true
      - properties:
          entries:
            type: array
            description: A list of legal hold policies
            items:
              $ref: '#/components/schemas/LegalHoldPolicy'
    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
          nullable: false
          enum:
          - user
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

        resources.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
            nullable: false
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
            nullable: false
    LegalHoldPolicy--Mini:
      title: Legal hold policy (Mini)
      type: object
      x-box-resource-id: legal_hold_policy--mini
      x-box-tag: legal_hold_policies
      x-box-variants:
      - mini
      - standard
      x-box-variant: mini
      description: A mini legal hold policy
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: The unique identifier for this legal hold policy
          example: '11446498'
        type:
          type: string
          description: '`legal_hold_policy`'
          example: legal_hold_policy
          enum:
          - legal_hold_policy
    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
          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