Box Developer Documentation
Log in
Latest version

Create user invite

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

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

Invites an existing external user to join an enterprise.

The existing user can not be part of another enterprise and must already have a Box account. Once invited, the user will receive an email and are prompted to accept the invitation within the Box web application.

This method requires the "Manage An Enterprise" scope enabled for the application, which can be enabled within the developer console.

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

objectin body

The user to invite

stringin bodyrequired
"john@example.com"

The login of the invited user

objectin body

The enterprise to invite the user to

stringin bodyrequired
"1232234"

The ID of the enterprise

Response

application/jsonInvite

Returns a new invite object.

application/jsonClient error

Returns not_found when user was not found.

application/jsonClient error

An unexpected client error.

post
Create user invite
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/invites" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "enterprise": {
         "id": "1232234"
       },
       "actionable_by": {
         "login" : "freeuser@box.com"
       }
     }'
TypeScript Gen
await client.invites.createInvite({
  enterprise: {
    id: currentUser.enterprise!.id!,
  } satisfies CreateInviteRequestBodyEnterpriseField,
  actionableBy: {
    login: email,
  } satisfies CreateInviteRequestBodyActionableByField,
} satisfies CreateInviteRequestBody);
Python Gen
client.invites.create_invite(
    CreateInviteEnterprise(id=current_user.enterprise.id),
    CreateInviteActionableBy(login=email),
)
.NET Gen
await client.Invites.CreateInviteAsync(requestBody: new CreateInviteRequestBody(enterprise: new CreateInviteRequestBodyEnterpriseField(id: NullableUtils.Unwrap(NullableUtils.Unwrap(currentUser.Enterprise).Id)), actionableBy: new CreateInviteRequestBodyActionableByField() { Login = email }));
Swift Gen (Beta)
try await client.invites.createInvite(requestBody: CreateInviteRequestBody(enterprise: CreateInviteRequestBodyEnterpriseField(id: currentUser.enterprise!.id!), actionableBy: CreateInviteRequestBodyActionableByField(login: email)))
Java
BoxUser user = new BoxUser(api, "0");
user.invite("Enterprise ID", "Invited User Login");
Python
enterprise = client.get_current_enterprise()
invitation = enterprise.invite_user('user@example.com')
Node
client.enterprise.inviteUser('1345', 'jsmith@box.com', callback);
iOS
client.users.inviteToJoinEnterprise(
    login: "user@example.com",
    enterpriseId: "12345"
) { (result: Result<Invite, BoxSDKError>) in
    guard case let .success(invite) = result else {
        print("Error inviting user to enterprise")
        return
    }

    print("Invited user \(invite.actionableBy.name) to \(invite.invitedTo.name)")
}

Response Example

{
  "id": "11446498",
  "type": "invite",
  "actionable_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "invited_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "invited_to": {
    "id": "11446498",
    "type": "enterprise",
    "name": "Acme Inc."
  },
  "modified_at": "2012-12-12T10:53:43-08:00",
  "status": "pending"
}