Sample - Box Platform API
POST/integration_mappings/teams

Create a Teams integration mapping

Creates a Teams integration mapping between a Teams channel and a Box folder. Supply partner_item and box_item, and ensure the authenticated user has the Admin or Co-Admin role before creating the mapping.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

2 body fields

Teams integration mapping details connecting a Teams channel to a Box folder.

partner_itemobjectrequired
The Teams item to map, including its required `id`, `type`, `tenant_id`, and `team_id` fields.
box_itemobjectrequired
The Box folder to associate with the Teams item, including its required `id` and `type` fields.

4 status codes
201Returns the created Teams integration mapping, including its identifiers, mapped Teams and Box items, mapping state, and timestamps.
idstringrequired
A unique identifier of a folder mapping (part of a composite key together with `integration_type`).
typestringrequired
Mapping type.
Allowed:integration_mapping
integration_typestringoptional
Identifies the Box partner app, with which the mapping is associated. Supports Slack and Teams. (part of the composite key together with `id`).
Allowed:teams
is_overridden_by_manual_mappingbooleanoptional
Identifies whether the mapping has been manually set by the team owner from UI for channels (as opposed to being automatically created).
partner_itemobjectrequired
Mapped item object for Teams.
box_itemobjectrequired
created_atstringoptional
When the integration mapping object was created.
modified_atstringoptional
When the integration mapping object was last modified.
400Returned when the Box folder cannot be mapped to the Teams item, including duplicate mappings, enterprise mismatches, external ownership, or invalid authorization.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
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.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returned when the integration mapping, Teams record, or Box folder cannot be found.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
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.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultReturned for an unexpected client error and includes a generic error object with a message and request identifier.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
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.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned when the Box folder cannot be mapped to partner_item, including when the channel, team, or folder is already mapped or the folder ownership is invalid. partner_item must include id, type, tenant_id, and team_id, while box_item must include id and type. A 404 is returned when the integration mapping, partner record, or Box folder cannot be found.