TL;DR: The ChangeTeam API moves one BoldSign user to another team in a single request. You can also hand that user’s documents to a colleague in the same call. Our eSignature API page covers the rest of the platform.
A sales rep moves to the partner team on Monday. Someone in IT has to open the admin pages, find the user, change the team and decide who keeps the open contracts. Done by hand, that job is easy to forget and hard to trace later.
The ChangeTeam API turns that job into one call your HR or IT system can make. This guide covers what the call does, what it needs and when to hand documents over.
What does the ChangeTeam API do?
The ChangeTeam API moves a user from one team to another. You can also tell us to give their documents to another user, or let them keep the documents.
Think of a desk move in an office. The person gets a new desk in another department. You decide whether their filing cabinet goes with them or stays for the person who takes over their work.
Teams are how you group users and control who sees which templates and documents. Our guide to managing teams with the BoldSign API shows how to create and list them. This post picks up after that, when a person needs to move.
Why move users between teams with code?
Code makes each move follow the same rules every time. Your HR system can call the endpoint as soon as a transfer is approved, so nobody has to remember the admin step.
People change roles, departments merge and new hires join the wrong team by mistake. Each change raises the same two questions: which team the user belongs to now, and who owns their documents.
Your logs also keep a record of each call. Each entry shows the user, the date and the new owner of their documents.
What does a ChangeTeam request need?
A request needs the user’s ID and the new team’s ID. A third value, the ID of a user who takes over the documents, is optional.
| Parameter | Where it goes | Required | What it holds |
|---|---|---|---|
userId |
Query string | Yes | The ID of the user you are moving |
toTeamId |
Request body | Yes | The ID of the team the user moves to |
transferDocumentsToUserId |
Request body | No | The ID of the user who receives the moved user’s documents |
You can copy the user ID from the users and teams pages in the web app. Our Users API guide shows how to list users and read their IDs from code.
What happens to documents and approvals during the move?
Two things change for the moved user beyond the team itself. Check both before you run the call in production.
- We decline or revoke any of the user’s documents that are still in progress.
- We revoke the user’s sender identity approvals.
- The user who takes over must ask those sender identities to approve them again.
- Until then, that user cannot open the documents sent on behalf of those identities.
Leave out transferDocumentsToUserId and the user keeps their documents in the new team.
How do you call the change team endpoint?
Send a PUT request to https://api.boldsign.com/v1/users/changeTeam. Put the userId in the query string, and put toTeamId in the request body.
Add transferDocumentsToUserId to the body to hand the documents to another user. Leave it out to let the user keep them.
The samples below move a user and hand their documents to a colleague. Each one after the command-line sample uses our software development kit (SDK) for that language. The developer reference notes that the C# sample needs SDK version 4.10.18-beta or later.
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"
}'
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);
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 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);
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);
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);
A successful call returns status code 200. Our change team reference lists the full request format.
When should you transfer documents with the move?
Transfer the documents when someone else will carry on the user’s work. Let the user keep them when they will still handle that work from the new team.
| Situation | Send transferDocumentsToUserId? |
Why |
|---|---|---|
| User changes team and keeps the same work | No | They still own and follow up their documents |
| User leaves the company | Yes | A manager or replacement takes over the documents |
| User’s workload passes to a new owner | Yes | The new owner needs control of the open work |
| Short move, and the user will come back | No | Ownership stays with the original user |
| You gather a team’s documents under one owner | Yes | One person becomes responsible for them |
Write these choices into your automation as fixed rules. Each move then follows the same path, and your logs make sense later.
What should you check before you move a user?
A few checks before each call save cleanup work afterwards. Build them into the code that calls the endpoint.
- Confirm the user and the new owner both still belong to your organization.
- Look up the team ID instead of typing it, so a typo cannot send the user elsewhere.
- Tell the new owner to request sender identity approval soon after the move.
- Log each call with the user, the old team, the new team and the new owner.
Send one request per user when you move a whole group. One failed call then stops one move, not the whole batch.
Which plan do you need to use the ChangeTeam API?
You can build and test the call in a free API sandbox account. Live calls need the Enterprise API plan.
The Enterprise API plan starts at $30 a month, billed yearly, with 40 envelopes a month. Each extra envelope costs $0.75, and the plan includes sender identities. Prices are in USD, and the pricing page has the current details.
Ready to move your first user with the API?
Try the call in the sandbox, then wire it into the system that tracks your staff changes.
- Create a free API sandbox account and send a test request.
- Book a demo to see how teams and users fit your account.
- Ask a question through our support portal.
Frequently asked questions
Can I move a user without moving their documents?
Yes. Send the userId and toTeamId, and leave out transferDocumentsToUserId. The user then keeps their documents in the new team.
When should I use transferDocumentsToUserId?
Use it when someone else should own the user's documents after the move. Typical cases are an employee leaving or handing work to a replacement.
What happens to documents that are still out for signature?
We decline or revoke them during the move. Plan the change for a moment when the user has few open documents, or resend them afterwards.
What happens to sender identity approvals when a user changes teams?
We revoke the moved user's sender identity approvals. The user who takes over the documents must ask those sender identities for approval again.
Where do I find the userId and team ID?
You can copy both from the users and teams pages in the web app. Your code can also read them from the list users and list teams endpoints.
How do I call the change team endpoint?
Send a PUT request to /v1/users/changeTeam. The userId goes in the query string, and the team and transfer IDs go in the request body.
Can I move several users in one request?
Each request moves one user. Loop over your list in code and send one request per user, then log each result.
Do I need a paid plan to try the ChangeTeam API?
You can test it in a free API sandbox account. Live calls need the Enterprise API plan, which starts at $30 a month billed yearly.