The ChangeTeam API is a BoldSign API endpoint that moves a user from one team to another. You can also transfer the user’s documents to another user to support handovers during role changes or offboarding. It’s intended for admins, platform teams, and developers who manage organizational structure and document ownership at scale. It helps reduce access and ownership gaps during reorganizations by applying consistent rules during team changes.
Why do teams need to move users between teams programmatically
As organizations grow, employees move to new projects, departments split, and responsibilities shift. When this happens, administrators face the burden of moving users, migrating their documents, and ensuring workflows continue without disruption.
Without automation, this process becomes slow, error-prone, and hard to audit. The ChangeTeam API solves this by allowing admins and developers to programmatically move users across teams and determine exactly what must happen to their documents. This unlocks smoother reorganizations, cleaner governance, and faster onboarding/offboarding processes.
How this endpoint moves users and their documents
The ChangeTeam API updates a user’s team assignment. When a user moves to a new team, you can decide whether to transfer ownership of their documents to another active user.
Which resource does the ChangeTeam API update
Understanding which system entities are updated during a team change helps clarify the impact of the API call and how it modifies ownership, access, and team relationships.
| Resource | Description |
|---|---|
| User | The user being moved to a new team |
| Team | The target team to which the user is reassigned |
| Documents | Optional transfer of document ownership to another user |
What parameters does the ChangeTeam API require
A request to this endpoint requires the user ID and team ID, and it also supports an optional parameter to transfer document ownership.
| Parameter | Requirement | Type | Description |
|---|---|---|---|
| userId | Required | String | The ID of the user being moved. |
| toTeamId | Required | String | The ID of the team to which the user will be transferred. |
| transferDocumentsToUserId | Optional | String | The ID of the target user who should receive all documents from the moved user while changing the team. |
These parameters let you control the user’s new team and whether document ownership is transferred.
What additional rules affect team changes and document access
Beyond the parameters, the API enforces rules that protect workflow integrity and compliance:
- If the user has documents that are currently in progress, those documents are declined or revoked during the change.
- Sender identity approvals associated with the moved user will be removed during the change and reassigned user will need to obtain approval again from those sender identities to access the on-behalf documents.
- If the user being moved is a team admin in their current team, their role is automatically changed to member in the new team.
- Both
userIdandtransferDocumentsToUserIdmust be active users who are not in deactivated or pending status.
These rules ensure that team changes do not leave documents in inconsistent or insecure states.
What operational benefits does the ChangeTeam API provide
Using an API-driven process improves consistency and auditability for team changes.
- Reduces manual admin steps for team changes and handovers.
- Makes ownership transfer explicit and auditable.
- Enforces validation rules (active users, valid team IDs) before changes are applied.
What endpoint do you call to change the team
Call the ChangeTeam endpoint with the userId in the query string and teamId in the request body. Optionally include transferDocumentsToUserId in request body to transfer document ownership as part of the move.
You can use this API in two main ways: moving only the user or moving the user and transferring their documents to another active user.
| Task | Method | Endpoint |
|---|---|---|
| Change User Team | PUT | https://api.boldsign.com/v1/users/changeTeam |
How do you change a user’s team with an API request and SDKs
The following examples demonstrate moving a user to a new team and transferring documents by setting transferDocumentsToUserId to the recipient user’s ID.
To transfer documents during the team change, set transferDocumentsToUserId. If you don’t want to transfer documents, omit transferDocumentsToUserId
cURL .NET Python PHP Java Node js
curl --location --request PUT 'https://api.boldsign.com/v1/users/changeTeam?userId=d98c14c5-60e0-411f-b02d-b39ca83c0da8' \
--header 'accept: */*' \
--header 'X-API-KEY: {apikey}' \
--header 'Content-Type: application/json' \
--data '{
"toTeamId": "9bca0986-xxx-xxxx-xxx-30ffe3a2c5b7",
"transferDocumentsToUserId": "8117b911-xxx-xxxx-xxx-819aab1e2bd5"
}'
.NET
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");
var userClient = new UserClient(apiClient);
var changeTeam = new ChangeTeam()
{
ToTeamId = "9bca0986-xxx-xxxx-xxx-30ffe3a2c5b7",
TransferDocumentsToUserId = "8117b911-xxx-xxxx-xxx-819aab1e2bd5"
};
await userClient.ChangeTeam("USER_ID", changeTeam);
Python
import sys
import os
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
import boldsign
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")
with boldsign.ApiClient(configuration) as api_client:
change_teams_api = boldsign.UserApi(api_client)
change_team = boldsign.ChangeTeamRequest(
to_team_id = "a175f8ac-xxxx-xxxx-94c4-3cc35fbad223",
transfer_documents_to_user_id = "32e67d6a-xxxx-xxxx-87f6-7def6c4c2845"
)
team_details_response = change_teams_api.change_team(
user_id="4b3c86ca-xxxx-xxxx-848f-66b0d476ef6b",
change_team_request= change_team
)
PHP
<?php require_once "vendor/autoload.php";
$config = new BoldSign\Configuration();
$config->setApiKey('YOUR_API_KEY');
$apiInstance = new BoldSign\Api\UserApi($config);
$changeTeam = new BoldSign\Model\ChangeTeamRequest();
$changeTeam->setToTeamId("28fb5768-xxxx-xxxx-a3dc-2449940c6b11");
$changeTeam->setTransferDocumentsToUserId("92d7236e-xxxx-xxxx-96ff-20522bab0abb");
$apiInstance->changeTeam("USER_ID",$changeTeam);
Java
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setApiKey("YOUR_API_KEY");
UserApi userApi = new UserApi(apiClient);
ChangeTeamRequest changeTeamRequest = new ChangeTeamRequest();
changeTeamRequest.setToTeamId("28fb5768-xxxx-xxxx-a3dc-2449940c6b11");
changeTeamRequest.setTransferDocumentsToUserId("4b3c86ca-xxxx-xxxx-848f-66b0d476ef6b");
userApi.changeTeam("USER_ID", changeTeamRequest);
Node js
import { UserApi, ChangeTeamRequest } from 'boldsign';
const userApi = new UserApi();
userApi.setApiKey("YOUR_API_KEY");
var changeTeam = new ChangeTeamRequest();
changeTeam.toTeamId = "28fb5768-xxxx-xxxx-xxxx-2449940c6b11";
changeTeam.transferDocumentsToUserId = "4b3c86ca-xxxx-xxxx-848f-66b0d476ef6b";
await userApi.changeTeam("USER_ID",changeTeam);
How this endpoint handle success and error responses
The ChangeTeam API uses standard HTTP status codes so integrations can detect success or failure.
Success response
- 200 OK: The user was moved and document transfer (if provided) completed.
Failure response
- 400 Bad Request: The input is invalid, and the API returns an error before any workflow action is executed.
Common error responses for this endpoint
The following errors may occur when using the ChangeTeam API. Each includes the error message and its meaning.
| Status Code | Error Message | Meaning |
|---|---|---|
| 400 | Invalid team ID | The target team is invalid. |
| 400 | User does not exist or does not belong to the organization | The specified user cannot be found in your organization. |
| 400 | User is already in the same team | The team change cannot be performed because the user is already part of the specified team. |
| 400 | The userId and the transferDocumentsToUserId cannot be the same | A user cannot transfer documents to themselves. |
| 400 | The userId cannot be in deactivated or pending status | Only active users can be moved or assigned documents. |
When to use vs. skip transferDocumentsToUserId
Knowing when to trigger document transfer is key to maintaining accurate ownership, reducing manual cleanup, and keeping workflows intact. The table below clarifies scenarios where document transfer is beneficial and where it is unnecessary.
| Case | Use transferDocumentsToUserId? | Reason |
|---|---|---|
| User is changing team but continues active work | No | The user should retain ownership of their own documents. |
| User is leaving the organization or being offboarded | Yes | Documents must be reassigned to a manager or replacement. |
| User is promoted and workload moves to a new owner | Yes | New owner needs control over existing documents. |
| Temporary team move where user will return | No | Document ownership should stay with the original user. |
| Cleanup or consolidation under a single owner | Yes | Centralizing documents under one responsible owner. |
This helps you design consistent rules in your automation for when to trigger document transfer.
Who should use the ChangeTeam API and why does it matter
Identifying the right teams and use cases ensures that automation is applied where it creates the most operational value and reduces manual effort.
This API is most useful for:
- Developers building HR, IT, or workflow automation integrations that must trigger team changes programmatically.
- IT administrators responsible for keeping team membership and access permissions aligned with organizational structure.
- HR and People Ops teams managing promotions, department moves, onboarding, or offboarding.
- Platform and governance teams ensuring document ownership always reflects real responsibilities.
Organizations with frequent team changes or role-based document ownership shifts gain the most value by automating these updates, ensuring accuracy and preventing document-access gaps.
What are common workflows for this endpoint
Practical scenarios demonstrate how organizations implement the the team‑change API to streamline user movement and document ownership transitions.
| Scenario | Inputs Used | What Happens |
|---|---|---|
| Onboarding into the correct team | userId + toTeamId | New hire placed immediately in the right team |
| Role transition with workload handover | userId + toTeamId + transferDocumentsToUserId | Documents move to a supervisor as user changes team |
| Offboarding an employee | userId + toTeamId + transferDocumentsToUserId | Documents reassigned to manager and user moved to archive team |
| Cross‑department restructure | userId + toTeamId | Team reorganization completed smoothly |
| Audit‑driven cleanup | userId + toTeamId + transferDocumentsToUserId | Document ownership aligned with compliance rules |
These practices help ensure your automation remains predictable and easy to troubleshoot.
What best practices help you use the ChangeTeam API reliably
Clear operational practices help ensure predictable, stable, and compliant automation when integrating the team‑change API into internal systems.
- Confirm both the moving user and the document recipient are in an active state.
- Validate the team ID before triggering user transfers.
- If sender identity approval is required in your organization, notify the document recipient and complete the approval step before transferring ownership.
- Maintain logs of all team changes and document transfers for governance and audits.
Following these practices ensures your integrations run smoothly at scale.
Final key takeaways:
The ChangeTeam API moves users between teams and can transfer document ownership when you need a clean handover. Use it in HR/IT/workflow automation to keep team membership and document ownership aligned with current responsibilities. Before enabling it in production, validate user status and team IDs, understand how in-progress documents are handled in your account, and log changes for auditability. For detailed guidance, see the official Change Team API documentation
Ready to streamline your signing workflows? Create a free BoldSign sandbox account and try it now.
We’d love your feedback—share your thoughts below. Need assistance? Reach us via the support portal or book a demo.
Related blogs
- Quartz.NET in Production: Advanced Job Scheduling for High-Traffic .NET APIs
- How to Download an Audit Trail PDF Using the BoldSign API
- BoldSign Sender Identity API – Send Documents Securely on Behalf of Others
Note: This blog was originally published at boldsign.com
Top comments (0)