Create shuttle job

{
  "id": "6a3ba68e810d9156194530a1",
  "type": "shuttle_job",
  "name": "Q4 SharePoint to Box",
  "job_type": "transfer",
  "state": "created",
  "mapping_state": "awaiting_path_mapping",
  "source_system": {
    "type": "shuttle_system",
    "id": "6a3ba68e810d9156194530a1",
    "name": "SharePoint"
  },
  "comment": "Migrating the finance department archives.",
  "account_mapping": {
    "is_enabled": true,
    "permission_conflict_strategy": "preserve_structure_restrict_sharing",
    "are_external_shares_mapped": false,
    "are_permissions_mapped": true
  },
  "tags": [
    "q4",
    "hr"
  ],
  "settings": {
    "bandwidth_limit_bytes_per_sec": 10485760,
    "are_deletions_mirrored": false,
    "are_file_versions_synced": true,
    "max_file_versions": 10,
    "is_overwrite_enabled": false,
    "are_completed_mappings_skipped_on_rerun": true,
    "is_content_scanning_enabled": false,
    "include_shared_source_folders": true,
    "include_shared_destination_folders": false
  }
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

POST

shuttle_jobs

{
  "id": "6a3ba68e810d9156194530a1",
  "type": "shuttle_job",
  "name": "Q4 SharePoint to Box",
  "job_type": "transfer",
  "state": "created",
  "mapping_state": "awaiting_path_mapping",
  "source_system": {
    "type": "shuttle_system",
    "id": "6a3ba68e810d9156194530a1",
    "name": "SharePoint"
  },
  "comment": "Migrating the finance department archives.",
  "account_mapping": {
    "is_enabled": true,
    "permission_conflict_strategy": "preserve_structure_restrict_sharing",
    "are_external_shares_mapped": false,
    "are_permissions_mapped": true
  },
  "tags": [
    "q4",
    "hr"
  ],
  "settings": {
    "bandwidth_limit_bytes_per_sec": 10485760,
    "are_deletions_mirrored": false,
    "are_file_versions_synced": true,
    "max_file_versions": 10,
    "is_overwrite_enabled": false,
    "are_completed_mappings_skipped_on_rerun": true,
    "is_content_scanning_enabled": false,
    "include_shared_source_folders": true,
    "include_shared_destination_folders": false
  }
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

Learn more about Box SDK versioning strategy.

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

box-version

enum<string>

required

Version header.

Available options:

2026.0

Body

application/json

The request body used to create a new shuttle job.

name

string

required

The human-readable name of the shuttle job.

Minimum string length: 1

Example:

"Q4 SharePoint to Box"

job_type

enum<string>

required

The type of work the shuttle job performs.

Available options:

transfer,

analysis

Example:

"transfer"

source_system_id

string

required

The unique identifier of the source system to migrate from.

Example:

"6a3ba68e810d9156194530a1"

comment

string

An optional free-form comment describing the shuttle job.

Example:

"Migrating the finance department archives."

Response

Returns the newly created shuttle job.

A standard representation of a shuttle job. A shuttle job describes a migration of content from a source system into Box, including its current state, mapping-preparation state, and mapping configuration.

string

required

The unique identifier for the shuttle job.

Example:

"6a3ba68e810d9156194530a1"

type

enum<string>

required

The value will always be shuttle_job.

Available options:

shuttle_job

Example:

"shuttle_job"

name

string

required

The human-readable name of the shuttle job.

Example:

"Q4 SharePoint to Box"

job_type

enum<string>

required

The type of work the shuttle job performs.

Available options:

transfer,

analysis

Example:

"transfer"

state

string

required

The current state of the shuttle job. This is an open string whose set of values is expected to grow; the currently documented values include created, started, stopped, completed, failed, invalid, and unknown. Clients should treat any value they do not recognize as unknown.

Example:

"created"

mapping_state

string

required

The current mapping-preparation state of the job. This is an open string whose set of values is expected to grow; the currently documented values include awaiting_path_mapping, importing_paths, paths_import_rejected, paths_invalid, paths_ready, scanning_source, source_scan_failed, source_scan_out_of_date, awaiting_subject_mapping, importing_subjects, subjects_import_rejected, mapping_complete, building_map, map_build_failed, map_out_of_date, and ready. paths_import_rejected means the last path-mapping spreadsheet was rejected or failed and the path mappings have not been changed since; it clears on the next import or the next manual path-mapping change. subjects_import_rejected means the last subject-mapping spreadsheet was rejected or failed and the subject mappings have not been changed since; it clears on the next import or the next manual subject-mapping change.

Example:

"awaiting_path_mapping"

source_system

object

required

The source system the shuttle job migrates content from.

Show child attributes

comment

string | null

An optional free-form comment describing the shuttle job.

Example:

"Migrating the finance department archives."

account_mapping

object

The account mapping configuration that controls how source identities and permissions are translated into Box.

Show child attributes

API reference

v2025.0

v2026.0

Authorizations

Headers

Body

Response