Users resources

Box API supports a variety of users, ranging from real employees logging in with their Managed User account, to applications using App Users to drive powerful automation workflows.

User

A standard representation of a user, as returned from any user API endpoints by default.

Attributes and example

Property	Type	Required	Description
id	string	Yes	The unique identifier for this user.
type	enum<string>	Yes	The value will always be user. Available options: user.
name	string	No	The display name of this user.
login	string	No	The primary email address of this user.
created_at	string	No	When the user object was created.
modified_at	string	No	When the user object was last modified.
language	string	No	The language of the user, formatted in modified version of the ISO 639-1 format.
timezone	string	No	The user’s timezone.
space_amount	integer	No	The user’s total available space amount in bytes.
space_used	integer	No	The amount of space in use by the user.
max_upload_size	integer	No	The maximum individual file size in bytes the user can have.
status	enum<string>	No	The user’s account status. Available options: active, inactive, cannot_delete_edit, cannot_delete_edit_upload.
job_title	string	No	The user’s job title.
phone	string	No	The user’s phone number.
address	string	No	The user’s address.
avatar_url	string	No	URL of the user’s avatar image.
notification_email	object	No	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. Can be null.

Example

{
  "id": "11446498",
  "type": "user",
  "name": "Aaron Levie",
  "login": "[e-mail]",
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "language": "en",
  "timezone": "Africa/Bujumbura",
  "space_amount": 11345156112,
  "space_used": 1237009912,
  "max_upload_size": 2147483648,
  "status": "active",
  "job_title": "CEO",
  "phone": "6509241374",
  "address": "900 Jefferson Ave, Redwood City, CA 94063",
  "avatar_url": "https://www.box.com/api/avatar/large/181216415",
  "notification_email": {
    "email": "[e-mail]",
    "is_confirmed": true
  }
}

User (Base)

A mini representation of a user, used when nested within another resource.

Attributes and example

Property	Type	Required	Description
id	string	Yes	The unique identifier for this user.
type	enum<string>	Yes	The value will always be user. Available options: user.

Example

{
  "id": "11446498",
  "type": "user"
}

User (Collaborations)

A mini representation of a user, can be returned only when the status is pending.

Attributes and example

Property	Type	Required	Description
id	string	Yes	The unique identifier for this user.
type	enum<string>	Yes	The value will always be user. Available options: user.
name	string	No	The display name of this user. If the collaboration status is pending, an empty string is returned.
login	string	No	The primary email address of this user. If the collaboration status is pending, a login value is returned.
is_active	boolean	No	If set to false, the user is either deactivated or deleted.

Example

{
  "id": "11446498",
  "type": "user",
  "name": "Aaron Levie",
  "login": "[e-mail]",
  "is_active": true
}

User (Full)

A full representation of a user, as can be returned from any user API endpoint.

Attributes and example

Property	Type	Required	Description
id	string	Yes	The unique identifier for this user.
type	enum<string>	Yes	The value will always be user. Available options: user.
name	string	No	The display name of this user.
login	string	No	The primary email address of this user.
created_at	string	No	When the user object was created.
modified_at	string	No	When the user object was last modified.
language	string	No	The language of the user, formatted in modified version of the ISO 639-1 format.
timezone	string	No	The user’s timezone.
space_amount	integer	No	The user’s total available space amount in bytes.
space_used	integer	No	The amount of space in use by the user.
max_upload_size	integer	No	The maximum individual file size in bytes the user can have.
status	enum<string>	No	The user’s account status. Available options: active, inactive, cannot_delete_edit, cannot_delete_edit_upload.
job_title	string	No	The user’s job title.
phone	string	No	The user’s phone number.
address	string	No	The user’s address.
avatar_url	string	No	URL of the user’s avatar image.
notification_email	object	No	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. Can be null.
role	enum<string>	No	The user’s enterprise role. Available options: admin, coadmin, user.
tracking_codes	array of Tracking code	No	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	boolean	No	Whether the user can see other enterprise users in their contact list.
is_sync_enabled	boolean	No	Whether the user can use Box Sync.
is_external_collab_restricted	boolean	No	Whether the user is allowed to collaborate with users outside their enterprise.
is_exempt_from_device_limits	boolean	No	Whether to exempt the user from Enterprise device limits.
is_exempt_from_login_verification	boolean	No	Whether the user must use two-factor authentication.
enterprise	object	No	A representation of a Box enterprise.
my_tags	array of string	No	Tags for all files and folders owned by the user. Values returned will only contain tags that were set by the requester.
hostname	string	No	The root (protocol, subdomain, domain) of any links that need to be generated for the user.
is_platform_access_only	boolean	No	Whether the user is an App User.
external_app_user_id	string	No	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.

Example

{
  "id": "11446498",
  "type": "user",
  "name": "Aaron Levie",
  "login": "[e-mail]",
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "language": "en",
  "timezone": "Africa/Bujumbura",
  "space_amount": 11345156112,
  "space_used": 1237009912,
  "max_upload_size": 2147483648,
  "status": "active",
  "job_title": "CEO",
  "phone": "6509241374",
  "address": "900 Jefferson Ave, Redwood City, CA 94063",
  "avatar_url": "https://www.box.com/api/avatar/large/181216415",
  "notification_email": {
    "email": "[e-mail]",
    "is_confirmed": true
  },
  "role": "admin",
  "tracking_codes": [
    {
      "type": "tracking_code",
      "name": "department",
      "value": "Sales"
    }
  ],
  "can_see_managed_users": true,
  "is_sync_enabled": true,
  "is_external_collab_restricted": true,
  "is_exempt_from_device_limits": true,
  "is_exempt_from_login_verification": true,
  "enterprise": {
    "id": "11446498",
    "type": "enterprise",
    "name": "Acme Inc."
  },
  "my_tags": [
    "important"
  ],
  "hostname": "https://example.app.box.com/",
  "is_platform_access_only": true,
  "external_app_user_id": "my-user-1234"
}

User (Integration Mappings)

A user representation for integration mappings API purposes. Fields name and login are not required.

Attributes and example

Property	Type	Required	Description
id	string	Yes	The unique identifier for this user.
type	enum<string>	Yes	The value will always be user. Available options: user.
name	string	No	The display name of this user.
login	string	No	The primary email address of this user.

Example

{
  "id": "11446498",
  "type": "user",
  "name": "Aaron Levie",
  "login": "[e-mail]"
}

User (Mini)

A mini representation of a user, as can be returned when nested within other resources.

Attributes and example

Property	Type	Required	Description
id	string	Yes	The unique identifier for this user.
type	enum<string>	Yes	The value will always be user. Available options: user.
name	string	No	The display name of this user.
login	string	No	The primary email address of this user.

Example

{
  "id": "11446498",
  "type": "user",
  "name": "Aaron Levie",
  "login": "[e-mail]"
}

Users

A list of users.

Attributes and example

Property	Type	Required	Description
limit	integer	No	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.
next_marker	string	No	The marker for the start of the next page of results. Can be null.
prev_marker	string	No	The marker for the start of the previous page of results. Can be null.
total_count	integer	No	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.
offset	integer	No	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.
order	array of object	No	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.
entries	array of User (Full)	No	A list of users.

Example

{
  "limit": 1000,
  "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
  "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
  "total_count": 5000,
  "offset": 2000,
  "order": [
    {
      "by": "type",
      "direction": "ASC"
    }
  ],
  "entries": [
    {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "[e-mail]",
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00",
      "language": "en",
      "timezone": "Africa/Bujumbura",
      "space_amount": 11345156112,
      "space_used": 1237009912,
      "max_upload_size": 2147483648,
      "status": "active",
      "job_title": "CEO",
      "phone": "6509241374",
      "address": "900 Jefferson Ave, Redwood City, CA 94063",
      "avatar_url": "https://www.box.com/api/avatar/large/181216415",
      "notification_email": {
        "email": "[e-mail]",
        "is_confirmed": true
      },
      "role": "admin",
      "tracking_codes": [
        {
          "type": "tracking_code",
          "name": "department",
          "value": "Sales"
        }
      ],
      "can_see_managed_users": true,
      "is_sync_enabled": true,
      "is_external_collab_restricted": true,
      "is_exempt_from_device_limits": true,
      "is_exempt_from_login_verification": true,
      "enterprise": {
        "id": "11446498",
        "type": "enterprise",
        "name": "Acme Inc."
      },
      "my_tags": [
        "important"
      ],
      "hostname": "https://example.app.box.com/",
      "is_platform_access_only": true,
      "external_app_user_id": "my-user-1234"
    }
  ]
}