Box Invites API
The Box Invites API allows inviting existing Box users to join an enterprise, managing the process of adding users to organizational accounts.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Invites API
description: Needs a description.
paths:
/invites:
post:
operationId: post_invites
summary: Box Create user invite
tags:
- Invites
x-box-tag: invites
description: |-
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.
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:
- enterprise
- actionable_by
properties:
enterprise:
type: object
description: The enterprise to invite the user to
required:
- id
properties:
id:
type: string
example: '1232234'
description: The ID of the enterprise
actionable_by:
type: object
description: The user to invite
required:
- id
properties:
login:
type: string
example: [email protected]
description: The login of the invited user
responses:
'200':
description: Returns a new invite object.
content:
application/json:
schema:
$ref: '#/components/schemas/Invite'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/invites/{invite_id}:
get:
operationId: get_invites_id
summary: Box Get user invite status
tags:
- Invites
description: Returns the status of a user invite.
x-box-tag: invites
parameters:
- name: invite_id
description: The ID of an invite.
example: '213723'
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 an invite object
content:
application/json:
schema:
$ref: '#/components/schemas/Invite'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
Invite:
title: Invite
type: object
x-box-resource-id: invite
x-box-tag: invites
description: An invite for a user to an enterprise.
required:
- id
- type
properties:
id:
type: string
description: The unique identifier for this invite
example: '11446498'
type:
type: string
description: '`invite`'
example: invite
enum:
- invite
invited_to:
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
actionable_by:
$ref: '#/components/schemas/User--Mini'
invited_by:
$ref: '#/components/schemas/User--Mini'
status:
description: The status of the invite
type: string
example: pending
created_at:
type: string
format: date-time
description: When the invite was created
example: '2012-12-12T10:53:43-08:00'
modified_at:
type: string
format: date-time
description: When the invite was modified.
example: '2012-12-12T10:53:43-08:00'
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
tags:
- name: Invites