openapi: 3.1.0 info: title: Box Users API description: Needs a description. paths: /users: get: operationId: get_users x-box-tag: users summary: Box List enterprise users tags: - Users description: >- Returns a list of all users for the Enterprise along with their `user_id`, `public_name`, and `login`. The application and the authenticated user need to have the permission to look up users in the entire enterprise. parameters: - name: filter_term description: |- Limits the results to only users who's `name` or `login` start with the search term. For externally managed users, the search term needs to completely match the in order to find the user, and it will only return one user at a time. in: query required: false example: john schema: type: string - name: user_type description: |- Limits the results to the kind of user specified. * `all` returns every kind of user for whom the `login` or `name` partially matches the `filter_term`. It will only return an external user if the login matches the `filter_term` completely, and in that case it will only return that user. * `managed` returns all managed and app users for whom the `login` or `name` partially matches the `filter_term`. * `external` returns all external users for whom the `login` matches the `filter_term` exactly. in: query required: false example: managed schema: type: string enum: - all - managed - external - name: external_app_user_id in: query required: false schema: type: string example: my-user-1234 description: |- Limits the results to app users with the given `external_app_user_id` value. When creating an app user, an `external_app_user_id` value can be set. This value can then be used in this endpoint to find any users that match that `external_app_user_id` value. - 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: 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 - 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: usemarker description: |- Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. in: query required: false example: true schema: type: boolean - 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 responses: '200': description: Returns all of the users in the enterprise. content: application/json: schema: $ref: '#/components/schemas/Users' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' post: operationId: post_users summary: Box Create user tags: - Users x-box-tag: users description: |- Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. 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 description: The name of the user example: Aaron Levie maxLength: 50 login: type: string description: |- The email address the user uses to log in Required, unless `is_platform_access_only` is set to `true`. example: boss@box.com is_platform_access_only: type: boolean example: true description: Specifies that the user is an app user. role: type: string enum: - coadmin - user description: The user’s enterprise role example: user language: type: string description: >- The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format. example: en is_sync_enabled: type: boolean description: Whether the user can use Box Sync example: true job_title: type: string description: The user’s job title maxLength: 100 example: CEO phone: type: string description: The user’s phone number maxLength: 100 example: '6509241374' address: type: string description: The user’s address maxLength: 255 example: 900 Jefferson Ave, Redwood City, CA 94063 space_amount: type: integer format: int64 description: >- The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage. example: 11345156112 tracking_codes: type: array items: $ref: '#/components/schemas/TrackingCode' description: >- Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. can_see_managed_users: type: boolean example: true description: |- Whether the user can see other enterprise users in their contact list timezone: type: string format: timezone description: The user's timezone example: Africa/Bujumbura is_external_collab_restricted: type: boolean example: true description: >- Whether the user is allowed to collaborate with users outside their enterprise is_exempt_from_device_limits: type: boolean example: true description: Whether to exempt the user from enterprise device limits is_exempt_from_login_verification: type: boolean example: true description: Whether the user must use two-factor authentication status: type: string enum: - active - inactive - cannot_delete_edit - cannot_delete_edit_upload description: The user's account status example: active external_app_user_id: type: string example: my-user-1234 description: >- An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. responses: '201': description: Returns a user object for the newly created user. content: application/json: schema: $ref: '#/components/schemas/User--Full' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /users/me: get: operationId: get_users_me x-box-tag: users summary: Box Get current user tags: - Users description: >- Retrieves information about the user who is currently authenticated. In the case of a client-side authenticated OAuth 2.0 application this will be the user who authorized the app. In the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default. Use the `As-User` header to change who this API call is made on behalf of. 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 responses: '200': description: Returns a single user object. content: application/json: schema: $ref: '#/components/schemas/User--Full' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /users/terminate_sessions: post: operationId: post_users_terminate_sessions summary: Box Create jobs to terminate users session tags: - Users x-box-tag: session_termination description: |- Validates the roles and permissions of the user, and creates asynchronous jobs to terminate the user's sessions. Returns the status for the POST request. requestBody: content: application/json: schema: type: object required: - user_ids - user_logins properties: user_ids: example: - '123456' - '456789' type: array description: A list of user IDs items: type: string user_logins: example: - user@sample.com - user2@sample.com type: array description: A list of user logins items: type: string responses: '202': description: Returns a message about the request status. content: application/json: schema: $ref: '#/components/schemas/SessionTerminationMessage' '400': description: |- Returns an error if some of the parameters are not valid. * `Users can not be NULL or EMPTY` when no value is provided * `User id format is string` when the provided user id format is incorrect * `Supported payload format is JSON` when the provided payload format is incorrect content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: Returns an error if there are insufficient permissions. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: Returns an error if the resource could not be found. content: application/json: schema: $ref: '#/components/schemas/ClientError' '429': description: Returns an error if the rate limit is exceeded. content: application/json: schema: $ref: '#/components/schemas/ClientError' '500': description: Returns an error if there is an internal server issue. content: application/json: schema: $ref: '#/components/schemas/ClientError' '503': description: Returns an error if the request timed out. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /users/{user_id}: get: operationId: get_users_id x-box-tag: users summary: Box Get user tags: - Users description: |- Retrieves information about a user in the enterprise. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for authenticated users with the right scopes. In this case, disallowed fields will return null instead. parameters: - name: user_id description: The ID of the user. example: '12345' 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 a single user object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields using the [fields](#get-users-id--request--fields) parameter. content: application/json: schema: $ref: '#/components/schemas/User--Full' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' put: operationId: put_users_id summary: Box Update user tags: - Users x-box-tag: users x-box-enable-explorer: true description: |- Updates a managed or app user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. parameters: - name: user_id description: The ID of the user. example: '12345' 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: enterprise: type: string nullable: true example: description: |- Set this to `null` to roll the user out of the enterprise and make them a free user notify: type: boolean example: true description: |- Whether the user should receive an email when they are rolled out of an enterprise name: type: string description: The name of the user example: Aaron Levie maxLength: 50 login: type: string description: |- The email address the user uses to log in Note: If the target user's email is not confirmed, then the primary login address cannot be changed. example: somename@box.com role: type: string enum: - coadmin - user description: The user’s enterprise role example: user language: type: string description: >- The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format. example: en is_sync_enabled: type: boolean description: Whether the user can use Box Sync example: true job_title: type: string description: The user’s job title maxLength: 100 example: CEO phone: type: string description: The user’s phone number maxLength: 100 example: '6509241374' address: type: string description: The user’s address maxLength: 255 example: 900 Jefferson Ave, Redwood City, CA 94063 tracking_codes: type: array items: $ref: '#/components/schemas/TrackingCode' description: >- Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. can_see_managed_users: type: boolean example: true description: |- Whether the user can see other enterprise users in their contact list timezone: type: string format: timezone description: The user's timezone example: Africa/Bujumbura is_external_collab_restricted: type: boolean example: true description: >- Whether the user is allowed to collaborate with users outside their enterprise is_exempt_from_device_limits: type: boolean example: true description: Whether to exempt the user from enterprise device limits is_exempt_from_login_verification: type: boolean example: true description: Whether the user must use two-factor authentication is_password_reset_required: type: boolean example: true description: Whether the user is required to reset their password status: type: string enum: - active - inactive - cannot_delete_edit - cannot_delete_edit_upload description: The user's account status example: active space_amount: type: integer format: int64 description: >- The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage. example: 11345156112 notification_email: type: object nullable: true description: |- An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address. Set this value to `null` to remove the notification email. properties: email: type: string example: notifications@example.com description: The email address to send the notifications to. external_app_user_id: type: string example: my-user-1234 description: >- An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. Note: In order to update this field, you need to request a token using the application that created the app user. responses: '200': description: Returns the updated user object. content: application/json: schema: $ref: '#/components/schemas/User--Full' '400': description: |- Returns an error if some of the parameters are missing or not valid. * `invalid_parameter` when a parameter is formatted incorrectly, for example when the `notification_email` has an incorrectly formatted email address. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: >- Returns an error if the user is not allowed to make the changes. * `access_denied_insufficient_permissions` when the user does not have the right permissions, for example when updating the notification email is turned off for the enterprise. * `denied_by_policy` when the user does not have the right permissions due to the information barrier restrictions. 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_users_id x-box-tag: users summary: Box Delete user tags: - Users description: |- Deletes a user. By default this will fail if the user still owns any content. Move their owned content first before proceeding, or use the `force` field to delete the user and their files. parameters: - name: user_id description: The ID of the user. example: '12345' in: path required: true schema: type: string - name: notify schema: type: boolean in: query example: true description: |- Whether the user will receive email notification of the deletion - name: force schema: type: boolean in: query example: true description: |- Whether the user should be deleted even if this user still own files responses: '204': description: Removes the user and returns an empty response. default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /users/{user_id}/avatar: get: operationId: get_users_id_avatar x-box-tag: avatars summary: Box Get user avatar tags: - Users description: Retrieves an image of a the user's avatar. parameters: - name: user_id description: The ID of the user. example: '12345' in: path required: true schema: type: string responses: '200': description: |- When an avatar can be found for the user the image data will be returned in the body of the response. content: image/jpg: schema: type: string format: binary description: The avatar default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' post: operationId: post_users_id_avatar x-box-tag: avatars summary: Box Add or update user avatar tags: - Users description: Adds or updates a user avatar. parameters: - name: user_id description: The ID of the user. example: '12345' in: path required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object required: - pic properties: pic: type: string format: binary description: |- The image file to be uploaded to Box. Accepted file extensions are `.jpg` or `.png`. The maximum file size is 1MB. responses: '200': description: |- * `ok`: Returns the `pic_urls` object with URLs to existing user avatars that were updated. content: application/json: schema: $ref: '#/components/schemas/UserAvatar' '201': description: |- * `created`: Returns the `pic_urls` object with URLS to user avatars uploaded to Box with the request. content: application/json: schema: $ref: '#/components/schemas/UserAvatar' '400': description: |- * `bad_request`: Returns an error when: * An image is not included in the request * The uploaded file is empty * The image size exceeds 1024 * 1024 pixels or 1MB * The file extension is other than `.jpg` or `.png`. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: >- * `forbidden`: Returns an error if the user does not have permissions necessary to upload an avatar or is not activated. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- * `not_found`: Returns an error if the user does not exist or cannot be found. 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_users_id_avatar x-box-tag: avatars summary: Box Delete user avatar tags: - Users description: |- Removes an existing user avatar. You cannot reverse this operation. parameters: - name: user_id description: The ID of the user. example: '12345' in: path required: true schema: type: string responses: '204': description: '* `no_content`: Removes the avatar and returns an empty response.' '403': description: >- * `forbidden`: Returned if the user does not have necessary permissions or is not activated. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: |- * `not_found`: Returned if the user or user avatar does not exist or cannot be found. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /users/{user_id}/folders/0: put: operationId: put_users_id_folders_0 x-box-tag: transfer summary: Box Transfer owned folders tags: - Users description: >- Move all of the items (files, folders and workflows) owned by a user into another user's account Only the root folder (`0`) can be transferred. Folders can only be moved across users by users with administrative permissions. All existing shared links and folder-level collaborations are transferred during the operation. Please note that while collaborations at the individual file-level are transferred during the operation, the collaborations are deleted when the original user is deleted. This call will be performed synchronously which might lead to a slow response when the source user has a large number of items in all of its folders. If the destination path has a metadata cascade policy attached to any of the parent folders, a metadata cascade operation will be kicked off asynchronously. There is currently no way to check for when this operation is finished. The destination folder's name will be in the format `{User}'s Files and Folders`, where `{User}` is the display name of the user. To make this API call your application will need to have the "Read and write all files and folders stored in Box" scope enabled. Please make sure the destination user has access to `Relay` or `Relay Lite`, and has access to the files and folders involved in the workflows being transferred. Admins will receive an email when the operation is completed. parameters: - name: user_id description: The ID of the user. example: '12345' 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 - name: notify description: |- Determines if users should receive email notification for the action performed. in: query required: false example: true schema: type: boolean requestBody: content: application/json: schema: type: object required: - owned_by properties: owned_by: type: object description: The user who the folder will be transferred to required: - id properties: id: type: string example: '1232234' description: |- The ID of the user who the folder will be transferred to responses: '200': description: |- Returns the information for the newly created destination folder. content: application/json: schema: $ref: '#/components/schemas/Folder--Full' '403': description: |- Returns an error when folder ownership cannot be transferred to another user. * `forbidden_by_policy`: Returned if ownership transfer is forbidden due to information barrier restrictions. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /users/{user_id}/email_aliases: get: operationId: get_users_id_email_aliases summary: Box List user's email aliases tags: - Users x-box-tag: email_aliases description: |- Retrieves all email aliases for a user. The collection does not include the primary login for the user. parameters: - name: user_id description: The ID of the user. example: '12345' in: path required: true schema: type: string responses: '200': description: Returns a collection of email aliases. content: application/json: schema: $ref: '#/components/schemas/EmailAliases' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' post: operationId: post_users_id_email_aliases x-box-tag: email_aliases summary: Box Create email alias tags: - Users description: Adds a new email alias to a user account.. parameters: - name: user_id description: The ID of the user. example: '12345' in: path required: true schema: type: string requestBody: content: application/json: schema: type: object required: - email properties: email: type: string example: alias@example.com description: |- The email address to add to the account as an alias. Note: The domain of the email alias needs to be registered to your enterprise. See the [domain verification guide]( https://support.box.com/hc/en-us/articles/4408619650579-Domain-Verification ) for steps to add a new domain. responses: '201': description: Returns the newly created email alias object. content: application/json: schema: $ref: '#/components/schemas/EmailAlias' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /users/{user_id}/email_aliases/{email_alias_id}: delete: operationId: delete_users_id_email_aliases_id x-box-tag: email_aliases summary: Box Remove email alias tags: - Users description: Removes an email alias from a user. parameters: - name: user_id description: The ID of the user. example: '12345' in: path required: true schema: type: string - name: email_alias_id description: The ID of the email alias. example: '23432' in: path required: true schema: type: string responses: '204': description: Removes the alias and returns an empty response. default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /users/{user_id}/memberships: get: operationId: get_users_id_memberships summary: Box List user's groups x-box-tag: memberships tags: - Users description: |- Retrieves all the groups for a user. Only members of this group or users with admin-level permissions will be able to use this API. parameters: - name: user_id description: The ID of the user. example: '12345' in: path required: true 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: 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 membership objects. If there are no memberships, an empty collection will be returned. content: application/json: schema: $ref: '#/components/schemas/GroupMemberships' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' components: schemas: Users: title: Users type: object x-box-resource-id: users x-box-tag: users description: A list of users. 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 users items: $ref: '#/components/schemas/User--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 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 User--Full: title: User (Full) type: object x-box-resource-id: user--full x-box-variant: full description: |- A full representation of a user, as can be returned from any user API endpoint. allOf: - $ref: '#/components/schemas/User' - properties: role: type: string enum: - admin - coadmin - user description: The user’s enterprise role example: admin tracking_codes: type: array items: $ref: '#/components/schemas/TrackingCode' description: |- Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. can_see_managed_users: type: boolean example: true description: >- Whether the user can see other enterprise users in their contact list is_sync_enabled: type: boolean description: Whether the user can use Box Sync example: true is_external_collab_restricted: type: boolean example: true description: >- Whether the user is allowed to collaborate with users outside their enterprise is_exempt_from_device_limits: type: boolean example: true description: Whether to exempt the user from Enterprise device limits is_exempt_from_login_verification: type: boolean example: true description: Whether the user must use two-factor authentication enterprise: allOf: - title: Enterprise type: object description: A representation of a Box enterprise properties: id: type: string description: The unique identifier for this enterprise. example: '11446498' type: type: string description: '`enterprise`' example: enterprise enum: - enterprise name: description: The name of the enterprise example: Acme Inc. type: string - description: Representation of the user’s enterprise my_tags: type: array items: type: string example: - important description: >- Tags for all files and folders owned by the user. Values returned will only contain tags that were set by the requester. hostname: type: string example: https://example.app.box.com/ description: >- The root (protocol, subdomain, domain) of any links that need to be generated for the user is_platform_access_only: type: boolean example: true description: Whether the user is an App User external_app_user_id: type: string example: my-user-1234 description: >- An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. UserAvatar: title: User avatar type: object x-box-resource-id: user_avatar x-box-tag: avatars description: |- A resource holding URLs to the avatar uploaded to a Box application. properties: pic_urls: type: object description: Represents an object with user avatar URLs. properties: small: type: string description: The location of a small-sized avatar. example: > https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!7B6R5cZLmurEV_xB-KkycPk8Oi7oENUX2O_qUtIuO4342CG IldyCto9hqiQP7uxqYU5V2w63Ft4ln4UVVLDtDZu903OqzkflY2O-Lq00 ubA29xU-RJ6b_KzJEWRYgUhX1zEl3dzWo12g8eWRE2rStf123DF7AYahNqM 1BmLmviL_nODc7SDQHedTXPAjxURUAra5BvtLe7B05AizbNXdPlCNp-LNh _S-eZ_RjDXcGO-MkRWd_3BOMHnvjf450t5BfKoJ15WhEfiMlfXH1tmouHXrsC 66cT6-pzF9E40Iir_zThqSlrFxzP_xcmXzHapr_k-0E2qr2TXp4iC396TSlEw large: type: string description: The location of a large-sized avatar. example: >- https://app.box.com/index.php?rm=pic_storage_auth&pic=euks pac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw jtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc gSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC ao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r preview: type: string description: The location of the avatar preview. example: >- https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW k-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ 04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl sSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc 9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g Folder--Full: title: Folder (Full) type: object x-box-resource-id: folder--full x-box-variant: full description: |- A full representation of a folder, as can be returned from any folder API endpoints by default allOf: - $ref: '#/components/schemas/Folder' - properties: sync_state: allOf: - type: string example: synced nullable: false description: |- Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive. enum: - synced - not_synced - partially_synced has_collaborations: type: boolean example: true nullable: false description: Specifies if this folder has any other collaborators. permissions: allOf: - type: object description: >- The permissions that the authenticated user has for a folder. required: - can_upload allOf: - type: object description: >- The permissions that the authenticated user has for an item. required: - can_delete - can_download - can_invite_collaborator - can_rename - can_set_share_access - can_share properties: can_delete: type: boolean description: Specifies if the current user can delete this item. example: true nullable: false can_download: type: boolean description: >- Specifies if the current user can download this item. example: true nullable: false can_invite_collaborator: type: boolean description: >- Specifies if the current user can invite new users to collaborate on this item, and if the user can update the role of a user already collaborated on this item. example: true nullable: false can_rename: type: boolean description: Specifies if the user can rename this item. example: true nullable: false can_set_share_access: type: boolean description: >- Specifies if the user can change the access level of an existing shared link on this item. example: true nullable: false can_share: type: boolean description: >- Specifies if the user can create a shared link for this item. example: true nullable: false - properties: can_upload: type: boolean description: Specifies if the user can upload into this folder. example: true nullable: false - description: |- Describes the permissions that the current user has for this folder - nullable: false tags: allOf: - type: array example: - approved items: type: string minItems: 1 maxItems: 100 description: |- The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise. - nullable: false can_non_owners_invite: allOf: - type: boolean example: true description: |- Specifies if users who are not the owner of the folder can invite new collaborators to the folder. - nullable: false is_externally_owned: type: boolean example: true nullable: false description: |- Specifies if this folder is owned by a user outside of the authenticated enterprise. metadata: allOf: - title: Item metadata instances type: object description: >- A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`. To access the metadata for a file or folder, first use the metadata endpoints to determine the metadata templates available to your enterprise. Then use the `GET /files/:id` or `GET /folder/:id` endpoint with the `fields` query parameter to get the metadata by ID. To request a metadata instance for a particular `scope` and `templateKey` use the following format for the `fields` parameter: `metadata..` For example, `?fields=metadata.enterprise_27335.marketingCollateral`. example: enterprise_27335: marketingCollateral: $canEdit: true $id: 01234500-12f1-1234-aa12-b1d234cb567e $parent: folder_59449484661 $scope: enterprise_27335 $template: marketingCollateral $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0 $typeVersion: 2 $version: 1 additionalProperties: type: object description: >- A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`. example: marketingCollateral: $canEdit: true $id: 01234500-12f1-1234-aa12-b1d234cb567e $parent: folder_59449484661 $scope: enterprise_27335 $template: marketingCollateral $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0 $typeVersion: 2 $version: 1 additionalProperties: $ref: '#/components/schemas/Metadata' - description: >- An object containing the metadata instances that have been attached to this folder. Each metadata instance is uniquely identified by its `scope` and `templateKey`. There can only be one instance of any metadata template attached to each folder. Each metadata instance is nested within an object with the `templateKey` as the key, which again itself is nested in an object with the `scope` as the key. is_collaboration_restricted_to_enterprise: allOf: - type: boolean example: true description: >- Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations. - nullable: false allowed_shared_link_access_levels: type: array example: - open items: type: string enum: - open - company - collaborators nullable: false description: |- A list of access levels that are available for this folder. For some folders, like the root folder, this will always be an empty list as sharing is not allowed at that level. allowed_invitee_roles: type: array example: - editor nullable: false description: |- A list of the types of roles that user can be invited at when sharing this folder. items: type: string enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner watermark_info: allOf: - type: object description: Details about the watermark applied to this item properties: is_watermarked: type: boolean description: Specifies if this item has a watermark applied. example: true nullable: false - description: Details about the watermark applied to this folder - nullable: false is_accessible_via_shared_link: type: boolean description: |- Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder. example: true enum: - true - false can_non_owners_view_collaborators: type: boolean example: true description: |- Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. classification: allOf: - type: object description: The classification applied to an item properties: name: type: string example: Top Secret description: The name of the classification definition: type: string example: Content that should not be shared outside the company. description: An explanation of the meaning of this classification. color: type: string example: '#FF0000' description: >- The color that is used to display the classification label in a user-interface. Colors are defined by the admin or co-admin who created the classification in the Box web app. - description: Details about the classification applied to this folder. - nullable: true EmailAliases: title: Email aliases type: object x-box-resource-id: email_aliases x-box-tag: email_aliases description: A list of email aliases properties: total_count: description: The number of email aliases. example: 5000 type: integer format: int64 entries: type: array description: A list of email aliases items: $ref: '#/components/schemas/EmailAlias' GroupMemberships: title: Group memberships type: object x-box-resource-id: group_memberships x-box-tag: memberships description: A list of group memberships. 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 group memberships items: $ref: '#/components/schemas/GroupMembership' tags: - name: Users