Box Developer Documentation
 
    Latest version

    Create user

    post
    https://api.box.com/2.0
    /users

    This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

    Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions.

    Request

    bearer [ACCESS_TOKEN]
    application/json

    Query Parameters

    string arrayin queryoptional
    id,type,name

    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.

    Request Body

    stringin bodyoptional
    "900 Jefferson Ave, Redwood City, CA 94063"
    255

    The user’s address

    booleanin bodyoptional
    true

    Whether the user can see other enterprise users in their contact list

    stringin bodyoptional
    "my-user-1234"

    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.

    booleanin bodyoptional
    true

    Whether to exempt the user from enterprise device limits

    booleanin bodyoptional
    true

    Whether the user must use two-factor authentication

    booleanin bodyoptional
    true

    Whether the user is allowed to collaborate with users outside their enterprise

    booleanin bodyoptional
    true

    Specifies that the user is an app user.

    booleanin bodyoptional
    true

    Whether the user can use Box Sync

    stringin bodyoptional
    "CEO"
    100

    The user’s job title

    stringin bodyoptional
    "en"

    The language of the user, formatted in modified version of the ISO 639-1 format.

    stringin bodyoptional
    "boss@box.com"

    The email address the user uses to log in

    Required, unless is_platform_access_only is set to true.

    stringin bodyrequired
    "Aaron Levie"
    50

    The name of the user

    stringin bodyoptional
    "6509241374"
    100

    The user’s phone number

    stringin bodyoptional
    "user"

    The user’s enterprise role

    Value is one of coadmin,user

    integer (int64)in bodyoptional
    11345156112

    The user’s total available space in bytes. Set this to -1 to indicate unlimited storage.

    stringin bodyoptional
    "active"

    The user's account status

    Value is one of active,inactive,cannot_delete_edit,cannot_delete_edit_upload

    string (timezone)in bodyoptional
    "Africa/Bujumbura"

    The user's timezone

    object arrayin bodyoptional

    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.

    stringin bodyoptional
    "tracking_code"

    tracking_code

    Value is always tracking_code

    stringin bodyoptional
    "department"

    The name of the tracking code, which must be preconfigured in the Admin Console

    stringin bodyoptional
    "Sales"

    The value of the tracking code

    Response

    application/jsonUser (Full)

    Returns a user object for the newly created user.

    application/jsonClient error

    An unexpected client error.

    post
    Create user
    You can now try out some of our APIs live, right here in the documentation.
    Log in

    Request Example

    cURL
    curl -i -X POST "https://api.box.com/2.0/users" \
         -H "authorization: Bearer <ACCESS_TOKEN>" \
         -H "content-type: application/json" \
         -d '{
           "login": "ceo@example.com",
           "name": "Aaron Levie"
         }'

    Response Example

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