> ## Documentation Index > Fetch the complete documentation index at: https://developer.box.com/llms.txt > Use this file to discover all available pages before exploring further. # Create shuttle subject mapping import > Accepts a spreadsheet of subject (user and group) mappings, already stored in Box, and replaces the job's subject mappings. A file that is not a subject-mapping workbook, or that exceeds the size or row limits (10 MiB Box download limit; 50,000 mapping rows), returns `400` synchronously and leaves the job unchanged. An accepted import always replaces every subject mapping on the job. When all rows are valid the workbook is deployed in full. When any row is invalid the job ends with no subject mappings and `mapping_state` becomes `subjects_import_rejected` until the next import or the next manual subject-mapping change. Row problems are listed by `GET /shuttle_mapping_errors?job_id=…` with category `subject_import`, messages of the form `Row N: …`, at most 500 entries plus one overflow entry. Validation and deployment are asynchronous after acceptance. Poll `GET /shuttle_jobs/{shuttle_job_id}` while `mapping_state` is `importing_subjects`. Only one import may be in flight per job. The job must map subjects (`account_mapping` enabled) and its source scan must be finished; otherwise the request returns `409`. Expected workbook format (API clients cannot download the UI template): sheets `Users` and/or `Groups` (a sheet named `Subjects` is also accepted). Columns are `Source User `, `Target User `, `Skip` on `Users`, and `Source Group `, `Target Group `, `Skip` on `Groups`, where `` is the primary identifier for that role and system: - Users: `Email` for most systems; `ID` for `SharePoint` (2007/2010/2013); `Name` for Windows (`windows_union`, stored as the user id). - Groups: `Name` for most systems; `Email` for Google Drive admin groups. Source rows for a template can be taken from `GET /shuttle_discovered_subjects`. > [!NOTE] > > Learn more about [Box SDK versioning strategy](https://developer.box.com/guides/tooling/sdks/sdk-versioning.md). ## OpenAPI ````yaml box-openapi-v2026.0.json POST /shuttle_subject_mapping_imports openapi: 3.0.2 info: title: Box Platform API description: >- [Box Platform](https://developer.box.com) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies. termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9 contact: name: Box, Inc url: https://developer.box.com email: devrel@box.com license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: '2026.0' x-box-commit-hash: da48f6b132 servers: - url: https://api.box.com/2.0 description: Box Platform API server. security: - OAuth2Security: [] tags: - name: Automate Workflows description: Endpoints for listing and manually starting Automate workflow actions. x-box-tag: automate_workflows - name: Convert to Box Note description: Create Box Notes from supported source content (for example Markdown). x-box-tag: notes - name: Document Split description: >- A set of endpoints used to split a paginated source document into multiple files based on user-defined or AI-generated page ranges. x-box-tag: document_split - name: Query description: Query for your items. x-box-tag: query - name: Shuttle description: >- Endpoints for managing Box Shuttle, the service that migrates content into Box from external sources. Use these endpoints to manage the systems that Shuttle migrates content from and the migration jobs that Shuttle runs. x-box-tag: shuttle externalDocs: description: Box Developer Documentation. url: https://developer.box.com paths: /shuttle_subject_mapping_imports: post: tags: - Shuttle summary: Create shuttle subject mapping import description: >- Accepts a spreadsheet of subject (user and group) mappings, already stored in Box, and replaces the job's subject mappings. A file that is not a subject-mapping workbook, or that exceeds the size or row limits (10 MiB Box download limit; 50,000 mapping rows), returns `400` synchronously and leaves the job unchanged. An accepted import always replaces every subject mapping on the job. When all rows are valid the workbook is deployed in full. When any row is invalid the job ends with no subject mappings and `mapping_state` becomes `subjects_import_rejected` until the next import or the next manual subject-mapping change. Row problems are listed by `GET /shuttle_mapping_errors?job_id=…` with category `subject_import`, messages of the form `Row N: …`, at most 500 entries plus one overflow entry. Validation and deployment are asynchronous after acceptance. Poll `GET /shuttle_jobs/{shuttle_job_id}` while `mapping_state` is `importing_subjects`. Only one import may be in flight per job. The job must map subjects (`account_mapping` enabled) and its source scan must be finished; otherwise the request returns `409`. Expected workbook format (API clients cannot download the UI template): sheets `Users` and/or `Groups` (a sheet named `Subjects` is also accepted). Columns are `Source User `, `Target User `, `Skip` on `Users`, and `Source Group `, `Target Group `, `Skip` on `Groups`, where `` is the primary identifier for that role and system: - Users: `Email` for most systems; `ID` for `SharePoint` (2007/2010/2013); `Name` for Windows (`windows_union`, stored as the user id). - Groups: `Name` for most systems; `Email` for Google Drive admin groups. Source rows for a template can be taken from `GET /shuttle_discovered_subjects`. operationId: post_shuttle_subject_mapping_imports_v2026.0 parameters: - $ref: '#/components/parameters/BoxVersionHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ShuttleSubjectMappingImportCreateRequest' examples: workbook: summary: Import subject mappings from a Box file value: job_id: 6a3ba68e810d9156194530a1 file_id: '12345678901' responses: '202': description: >- The import was accepted. Validation and deployment continue asynchronously. Poll `GET /shuttle_jobs/{shuttle_job_id}` until `mapping_state` is no longer `importing_subjects`. A rejected import ends with `mapping_state` `subjects_import_rejected` and an empty subject-mapping list; a successful import moves on to a later mapping-preparation state such as `mapping_complete` or `ready`. '400': description: >- Returned when the request body is malformed or fails request validation, or when the referenced file cannot be accepted as a subject-mapping workbook (for example it is not a spreadsheet, has none of the `Users`, `Groups`, or `Subjects` sheets, or exceeds the size or row limits). Nothing is stored and the job's subject mappings are unchanged. Row-level mapping errors are not returned here; after a `202` they finish asynchronously as `subjects_import_rejected` and appear on `GET /shuttle_mapping_errors`. content: application/json: schema: $ref: '#/components/schemas/ClientError' '401': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: >- Returned when the authenticated user is not an admin or co-admin with permission to manage enterprise properties. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returned when the shuttle job is not found, or the referenced file does not exist or cannot be read by the authenticated user. content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: >- Returned when an import is already in progress for the shuttle job, the job does not map subjects, or the source scan has not finished (or is out of date relative to the current path mappings). content: application/json: schema: $ref: '#/components/schemas/ClientError' '429': description: >- Returned when the user has sent too many requests in a given amount of time. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' components: parameters: BoxVersionHeader: name: box-version in: header description: Version header. allowEmptyValue: false required: true schema: type: string enum: - '2026.0' example: '2026.0' schemas: ShuttleSubjectMappingImportCreateRequest: description: >- The request body used to import a shuttle job's subject mappings from a spreadsheet already stored in Box. type: object properties: job_id: description: >- The unique identifier of the shuttle job whose subject mappings are replaced. type: string example: 6a3ba68e810d9156194530a1 file_id: description: >- The unique identifier of the Box file holding the mapping workbook. The file is read as the calling user, so it must live somewhere that user can download from. type: string example: '12345678901' required: - job_id - file_id title: Shuttle subject mapping import create request x-box-resource-id: shuttle_subject_mapping_import_create_request_v2026.0 x-box-tag: shuttle ClientError: description: A generic error. type: object properties: type: description: The value will always be `error`. type: string example: error enum: - error nullable: false status: description: The HTTP status of the response. type: integer format: int32 example: 400 nullable: false code: description: A Box-specific error code. type: string example: item_name_invalid 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. type: string example: Method Not Allowed 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 example: message: Something went wrong additionalProperties: {} nullable: true help_url: description: A URL that links to more information about why this error occurred. type: string example: >- https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/ 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 title: Client error x-box-resource-id: client_error_v2026.0 securitySchemes: OAuth2Security: type: oauth2 description: >- The access token received from the authorization server in the OAuth 2.0 flow. flows: authorizationCode: authorizationUrl: https://account.box.com/api/oauth2/authorize tokenUrl: https://api.box.com/oauth2/token scopes: root_readonly: Read all files and folders stored in Box root_readwrite: Read and write all files and folders stored in Box manage_app_users: Provision and manage app users manage_managed_users: Provision and manage managed users manage_groups: Manage an enterprise's groups manage_webhook: Create webhooks programmatically through the API manage_enterprise_properties: Manage enterprise properties manage_data_retention: Manage data retention polices manage_legal_hold: Manage Legal Holds ````