User moves in Webex Calling involve transferring users from one location to another within the same organization, along with their associated phone numbers and/or extensions, or assigning new ones as needed. For further details on features that are retained/removed during a move, see the Features section in Move Calling users help document.

anchorExploring the Move User Workflows

The Move User APIs support both single-user and bulk operations, with the ability to move up to 100 users in a single request. These APIs provide several distinct workflows designed to handle different aspects of the user relocation process. The workflows can be grouped into validation, execution, and monitoring categories, each serving specific operational needs:

Validation Workflow

Validate Move Users Job with allows administrators to preview the impact of moving users before executing the actual move operation. This enables administrators to perform a complete set of validations, returning the results synchronously. The initial request validations are performed first, and if no errors are found at this stage, the system proceeds with comprehensive request validations and returns detailed impacts and errors arrays that help administrators understand the potential impacts of proceeding with the move, as well as any hard stops that may prevent the move.

Note: The validation workflow is supported only for single calling user moves.

Move Execution Workflow

Execute Move Users Job with performs the actual user relocation. This workflow supports both calling and non-calling user moves. Initial request validations are performed first, and only if these pass does the system proceed with the actual user move.

For a single non-calling user, no job is created and the move executes synchronously.

On the other hand, for a single calling user or bulk user moves, a job is created. A job is created for asynchronous operations, showing up in Control Hub as a task. Each job may execute multiple steps that can be monitored for progress and completion status, predominantly used for bulk processing of records. During move user job execution, additional comprehensive request validation errors may occur, which can be viewed via the List Move Users Job Errors API or CSV downloads from the Get Move Users Job Status API.

Job Monitoring and Status Workflow

For all jobs, corresponding monitoring APIs are defined that provide real-time visibility into job progress, completion status, and detailed error reporting. For the move user jobs, it consists of the below APIs:

• List Move Users Jobs retrieves all move jobs for an organization, ordered by most recent first, with status information and completion counts.
• Get Move Users Job Status provides detailed status information for a specific job, including execution timestamps, step-by-step progress, and CSV download links for detailed results.
• List Move Users Job Errors returns detailed error information for a specific job that completed with errors, helping administrators identify and resolve specific user move failures.

The monitoring capabilities include:

• Real-time status tracking with job execution states (STARTED, COMPLETED, COMPLETED_WITH_ERRORS, FAILED)
• Progress counters showing total moves, successful moves, failed moves, and pending moves
• Detailed error reporting with specific error codes and messages for troubleshooting
• CSV export functionality for comprehensive move results and audit trails

anchorGetting Started

The Move User APIs require full administrator privileges and specific scopes for execution. Begin by ensuring you have the proper authentication and permissions, then follow a validation-first approach to minimize disruption during user moves.

Prerequisites

• Full administrator auth token with scopes: spark-admin:telephony_config_write, spark-admin:people_write, and identity:groups_rw
• Read-only administrator auth token (for monitoring operations) with scope: spark-admin:telephony_config_read
• Webex Calling enabled organization with multiple locations configured

Recommended Workflow

1. Plan the move by identifying source and target locations, users to be moved, and desired phone numbers/extensions
2. Validate first if it is for a single calling user using validate: true to identify all potential errors and impacts (see Validation Workflow)
3. Resolve errors identified from the validation workflow
4. Execute the move using validate: false after validation is clean (for a single calling user) or directly for bulk operations
5. Monitor progress using the job status APIs for asynchronous move operations
6. Handle errors by reviewing detailed error reports and retrying failed moves after resolution

anchorCommon Error Codes and Responses

The Move User APIs return specific error codes to help identify and resolve issues during validation and execution. Understanding these error codes is essential for proper error handling and troubleshooting.

HTTP Status Codes

Validation Error Codes

The Move User APIs use different categories of validation error codes depending on when validation occurs in the request lifecycle. Understanding these categories helps with proper error handling and troubleshooting.

Hard Stop Validation Errors

Typically, all validation failures for a user move request will be consolidated and returned together. This means that if a user has multiple validation issues, all errors will be collected and returned together, allowing administrators to address all problems in one iteration.

However, there are certain exceptions where validation consolidation does not apply and the request is rejected immediately. Some of these cases include:

• Request has more users than the allowed limit
• Request JSON syntax errors - Malformed JSON prevents further processing
• JSON parse errors - Invalid JSON structure stops validation
• Malformed Webex resource type - Fundamental format issues
• Duplicate users and empty users - Their related fields (locationId/extension/phoneNumber) are not validated, but other unique users in the request are still validated

Initial Request Validation Errors

For all requests, regardless of the validate attribute value, a basic set of validations is performed synchronously. These validations include basic request format checks, user ID validation, and business rule verification. Any validation failures at this stage are returned synchronously in the errors array field of the error response with the appropriate error codes and status code 400.

The possible error codes that can occur during initial API request validation include:

Comprehensive Request Validation Errors

These error codes can occur during comprehensive validation of user moves.

When the validate attribute is set to true for a single calling user, these errors are returned synchronously in the errors array field of the validation response with the status code 200.

When the validate attribute is set to false, these errors are validated during job execution and can be found via the List Move Users Job Errors API in the items[].error field, and the CSV download from the Get Move Users Job Status API.

The possible validation errors are:

Impact Codes

These impact codes indicate changes that will occur during the user move.

When the validate attribute is set to true for a single calling user, these impacts are returned synchronously in the impacts array field of the validation response with the status code 200.

When the validate attribute is set to false, these impacts are available during job execution and can be found in the CSV download from the Get Move Users Job Status API.

The possible impacts are:

Request Format Examples

Single User Validation Request

{
  "usersList": [
    {
      "locationId": "Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzMxMTkwZjQtZjBiOS00",
      "validate": true,
      "users": [
        {
          "userId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS8xZTJjNzBlZC00ZDYtNGYyYy05",
          "extension": "1001",
          "phoneNumber": "+18632520486"
        }
      ]
    }
  ]
}

Single User Move Request

{
  "usersList": [
    {
      "locationId": "Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzMxMTkwZjQtZjBiOS00",
      "validate": false,
      "users": [
        {
          "userId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS8xZTJjNzBlZC00ZDYtNGYyYy05",
          "extension": "1001",
          "phoneNumber": "+18632520486"
        }
      ]
    }
  ]
}

Bulk User Move Request

{
    "usersList": [
        {
            "locationId": "Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzVmMDI3OGZlLWU4OGMtNDMzNy04MGViLWRjY2NiM2VlMDU1MA",
            "validate": false,
            "users": [
                {
                    "userId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9teW5hbWUgaXNvcHRpdXMGEyltZXdlYXJlMGEyMGEyNWM1OWE",
                    "phoneNumber": "+18632520486"
                },
                {
                    "userId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS8wNTJhYjliZC1jNmUyLTZlYWUtMWE5YS01ZWZhMGEyNWMxNmE",
                    "extension": "28544"
                }
            ]
        },
        {
            "locationId": "Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzVmMDI3OGZlLWU4OGMtNDkwNS04MGViLWRjY2NiM2VlMTQ0MwFG",
            "validate": false,
            "users": [
                {
                    "userId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS85YzJhMDUxMC0wOTUwLTQ1MmYtODFmZi05YTVkMjM2OTJkZTY",
                    "extension": "29376",
                    "phoneNumber": "+18947028597"
                }
            ]
        }
    ]
}

Response Format Examples

Error Response

Error responses follow a consistent format with detailed error information:

{
    "errors": [
        {
            "code": 1026016,
            "message": "User should have either phone number or extension."
        }
    ]
}

Internal Server Error Response

For internal server errors, the response will be of the format:

{
    "message": "The request could not be understood by the server due to malformed syntax.",
    "errors": [
        {
            "description": "The request could not be understood by the server due to malformed syntax."
        }
    ]
}

Validation Response

Validation results with information on possible impacts and errors if any:

{
    "response": {
        "usersList": [
            {
                "userId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS85YzJhMDUxMC0wOTUwLTQ1MmYtODFmZi05YTVkMjM2OTJkZTY",
                "impacts": [
                    {
                        "code": 19701,
                        "message": "[Informational 19701] The identity/device profile the user is using is moved to the new group: GBKAXBRMJUXF, GNXX95CLTQ0V, HD_92dbc8b6-30d1-419f-9386-3340da658f9c, G4O4NVP7MZI5, GQGWO5BDMPLP."
                    },
                    {
                        "code": 19722,
                        "message": "[Informational 19722] User CLID number is set to use the new group CLID number: null."
                    },
                    {
                        "code": 19723,
                        "message": "[Informational 19723] New group CLID number is not configured."
                    }
                ],
                "errors": [
                    {
                        "code": 4202,
                        "message": "[Error 4202] The extension is not available. It is already assigned to a user: 7593. "
                    }
                ]
            }
        ]
    }
}

Job Response

Successful job creation returns detailed job information:

{
    "response": {
        "jobDetails": {
            "name": "moveusers",
            "id": "Y2lzY29zcGFyazovL3VzL0pPQl9JRC9mZjBlN2Q2Ni05MDRlLTRkZGItYjJlNS05ZGM0ODk0ZDY5OTk",
            "trackingId": "ROUTER_ebb52b5b-d060-4164-9757-48b383423d73",
            "sourceUserId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS85YzJhMDUxMC0wOTUwLTQ1MmYtODFmZi05YTVkMjM2OTJkZTY",
            "sourceCustomerId": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wMjEyNGVlZi04YWY3LTQ4OWMtODA1Yi0zNjNjYzY0MDE4OTM",
            "targetCustomerId": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wMjEyNGVlZi04YWY3LTQ4OWMtODA1Yi0zNjNjYzY0MDE4OTM",
            "instanceId": 10,
            "jobExecutionStatus": [
                {
                    "id": 10,
                    "startTime": "2023-06-08T12:05:11.798Z",
                    "lastUpdated": "2023-06-08T12:05:11.798Z",
                    "statusMessage": "STARTED",
                    "exitCode": "UNKNOWN",
                    "createdTime": "2023-06-08T12:05:11.752Z",
                    "timeElapsed": "PT0S"
                }
            ],
            "latestExecutionStatus": "STARTED",
            "latestExecutionExitCode": "UNKNOWN",
            "counts": {
                "totalMoves": 0,
                "moved": 0,
                "failed": 0,
                "pending": 0,
                "skipped": 0
            }
        }
    }
}