> ## 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.

# Update shuttle subject mapping

> Updates the mutable properties of an existing shuttle subject mapping identified by its ID. Only the fields supplied in the request body are changed.

> [!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 PUT /shuttle_subject_mappings/{shuttle_subject_mapping_id}
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_mappings/{shuttle_subject_mapping_id}:
    put:
      tags:
        - Shuttle
      summary: Update shuttle subject mapping
      description: >-
        Updates the mutable properties of an existing shuttle subject mapping
        identified by its ID. Only the fields supplied in the request body are
        changed.
      operationId: put_shuttle_subject_mappings_id_v2026.0
      parameters:
        - $ref: '#/components/parameters/BoxVersionHeader'
        - name: shuttle_subject_mapping_id
          in: path
          description: The unique identifier for the shuttle subject mapping.
          required: true
          schema:
            type: string
          example: 6a3ba7b12ea17bc9461eeace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShuttleSubjectMappingUpdateRequest'
            examples:
              skip_subject:
                summary: Skip a mapped subject
                value:
                  is_subject_skipped: true
              remap_subject:
                summary: Map a subject to a Box user
                value:
                  is_subject_skipped: false
                  target:
                    type: user
                    id: '12345678'
      responses:
        '200':
          description: Returns the updated shuttle subject mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShuttleSubjectMapping'
        '400':
          description: >-
            Returned when the request body is malformed, empty, or fails
            validation.
          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 subject mapping is not found or the user
            does not have access to it.
          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:
    ShuttleSubjectMappingUpdateRequest:
      description: >-
        The request body used to update an existing shuttle subject mapping.
        Only the fields supplied in the request body are changed. `job_id`,
        `id`, `type`, `source`, `discovered_subject_id`, and `revision` are
        immutable.
      type: object
      properties:
        is_subject_skipped:
          description: Whether this subject should be skipped during the migration.
          type: boolean
          example: true
        target:
          description: >-
            The Box target to map to. Set to `null` only for a skipped subject.
            Setting it to `null` while the mapping is active fails validation.
            Updating `is_subject_skipped` alone preserves the existing target.
          example:
            type: user
            id: '12345678'
          oneOf:
            - $ref: '#/components/schemas/ShuttleTargetSubjectInput'
            - title: OpenAPI 3.0 null schema type
              description: The definition for a null schema type in OpenAPI `3.0`.
              type: object
              nullable: true
              additionalProperties: false
      minProperties: 1
      title: Shuttle subject mapping update request
      x-box-resource-id: shuttle_subject_mapping_update_request_v2026.0
      x-box-tag: shuttle
    ShuttleSubjectMapping:
      description: >-
        A standard representation of a shuttle subject mapping. A subject
        mapping connects a discovered source subject to a Box user or group, or
        marks the subject as skipped.
      type: object
      properties:
        id:
          description: The unique identifier for the shuttle subject mapping.
          type: string
          example: 6a3ba7b12ea17bc9461eeace
        type:
          description: The value will always be `shuttle_subject_mapping`.
          type: string
          example: shuttle_subject_mapping
          enum:
            - shuttle_subject_mapping
        job_id:
          description: The unique identifier of the shuttle job this mapping belongs to.
          type: string
          example: 6a3ba68e810d9156194530a1
        discovered_subject_id:
          description: >-
            The unique identifier of the discovered subject this mapping applies
            to. `null` for legacy mappings created before this field was
            tracked.
          type: string
          example: 6a3ba7c02ea17bc9461eeacf
          nullable: true
        revision:
          description: >-
            The discovery-requirements revision this mapping was resolved
            against. `null` for legacy mappings.
          type: integer
          format: int32
          example: 3
          nullable: true
        is_subject_skipped:
          description: Whether this subject is skipped during the migration.
          type: boolean
          example: false
        source:
          allOf:
            - $ref: '#/components/schemas/ShuttleSubject'
            - description: The source subject being mapped.
        target:
          description: >-
            The Box target subject. `null` when the subject is skipped or not
            yet assigned.
          example:
            type: user
            id: '12345678'
            email: jane.doe@company.box.com
            name: Jane Doe
          oneOf:
            - $ref: '#/components/schemas/ShuttleTargetSubject'
            - title: OpenAPI 3.0 null schema type
              description: The definition for a null schema type in OpenAPI `3.0`.
              type: object
              nullable: true
              additionalProperties: false
      required:
        - id
        - type
        - job_id
        - is_subject_skipped
        - source
      title: Shuttle subject mapping
      x-box-resource-id: shuttle_subject_mapping_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
    ShuttleTargetSubjectInput:
      description: A Box user or group to map a source subject to.
      type: object
      properties:
        type:
          description: Whether the Box target is a user or a group.
          type: string
          example: user
          enum:
            - user
            - group
        id:
          description: The identifier of the target Box subject.
          type: string
          example: '12345678'
      required:
        - type
        - id
      title: Shuttle target subject input
      x-box-resource-id: shuttle_target_subject_input_v2026.0
      x-box-tag: shuttle
    ShuttleSubject:
      description: >-
        A subject discovered on the source migration system, such as a user or
        group.
      type: object
      properties:
        type:
          description: Whether this subject is a user or a group.
          type: string
          example: user
          enum:
            - user
            - group
        id:
          description: >-
            The platform-native identifier of the subject. `null` when the
            system does not provide one.
          type: string
          example: sp-user-001
          nullable: true
        email:
          description: The email address of the subject. `null` when unknown.
          type: string
          example: user@example.com
          nullable: true
        name:
          description: The display name of the subject. `null` when unknown.
          type: string
          example: Jane Doe
          nullable: true
        roles:
          description: >-
            Roles this subject holds on the source. `null` when no roles are
            known.
          type: array
          items:
            $ref: '#/components/schemas/ShuttleSubjectRole'
          example:
            - owner
          nullable: true
      required:
        - type
      title: Shuttle subject
      x-box-resource-id: shuttle_subject_v2026.0
      x-box-tag: shuttle
    ShuttleTargetSubject:
      description: A Box user or group that a source subject is mapped to.
      type: object
      properties:
        type:
          description: Whether the Box target is a user or a group.
          type: string
          example: user
          enum:
            - user
            - group
        id:
          description: >-
            The Box user or group ID. `null` when the mapping was not created
            through this API and is identified by email (user) or name (group)
            instead. Skip is represented by `target: null`, not a missing `id`.
            Create and update always send `id`.
          type: string
          example: '12345678'
          nullable: true
        email:
          description: The email address of the target. `null` when unknown.
          type: string
          example: user@example.com
          nullable: true
        name:
          description: The display name of the target. `null` when unknown.
          type: string
          example: Jane Doe
          nullable: true
      required:
        - type
      title: Shuttle target subject
      x-box-resource-id: shuttle_target_subject_v2026.0
      x-box-tag: shuttle
    ShuttleSubjectRole:
      description: A role a source subject holds on the source system.
      type: string
      example: owner
      enum:
        - owner
        - creator
        - updater
        - namespace_account
        - sharee
        - account_holder
        - unknown
      title: Shuttle subject role
      x-box-tag: shuttle
  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

````