Skip to content
  1. Blog
  2. API

Create and Manage Users with the BoldSign Users API

TL;DR: The BoldSign Users API lets your app invite users, give them a team and a role, and manage them later from code. You can list and fetch users, change roles, resend or cancel invitations, update metadata and move users between teams. Our eSignature API page covers the rest of the platform.

A new customer signs up for your app and needs 12 colleagues set up for signing. Adding each one by hand in the BoldSign web app takes time, and people can end up on the wrong team.

The Users API moves that work into your onboarding code. This guide is for developers who build on a SaaS eSignature API and want user setup to happen the same way every time.

What is the BoldSign Users API?

The Users API is a set of endpoints for the people in your BoldSign organization. Your app can invite, list, update and move users without anyone opening the web app.

Think of a hotel front desk. Staff hand out key cards, choose which floors each card opens and cancel cards that guests never collect. The Users API does the same for the people who send documents from your account.

What can you automate with the BoldSign Users API?

You can cover most of a user’s life in your organization, from the first invite to a team change.

  • Invite several users at once by email address.
  • Place each user on a team with the Admin, TeamAdmin or Member role.
  • List and fetch users to check who is set up.
  • Resend or cancel invitations that are still pending.
  • Update user metadata and move users between teams.

What do you need before you start?

You need an account, a way to sign in to the API and a tool that sends web requests.

Send your API key in the X-API-KEY header. With OAuth, send Authorization: Bearer <access_token> instead.

The examples below use an API key. Our post on API keys and OAuth explains when to pick each.

Which Users API endpoints does this guide use?

All eight calls go to https://api.boldsign.com. The metadata endpoint sits under /v1-beta, and the rest sit under /v1.

Task Method Endpoint
Invite (create) users POST /v1/users/create
List users GET /v1/users/list
Get one user GET /v1/users/get
Update a user’s role PUT /v1/users/update
Resend an invitation POST /v1/users/resendInvitation
Cancel an invitation POST /v1/users/cancelInvitation
Update user metadata PUT /v1-beta/users/updateMetaData
Move a user to another team PUT /v1/users/changeTeam

How do you provision users during app onboarding?

Map each of your customers to a BoldSign organization, then run the same short sequence for every new user. Here is the order this guide follows.

  1. List teams and pick a team ID.
  2. Invite the users and keep the userId that comes back.
  3. List or get the users to confirm their status, role and team.
  4. Change a role, or resend or cancel an invite, as needed.
  5. Update metadata or move a user to a new team when things change.

How do you create and manage BoldSign users step by step?

Work through the steps below in order the first time. After that, call each endpoint whenever your app needs it.

Step 1: Authenticate your requests

Add your API key or OAuth token to the header of every request. Keep keys and tokens on your server, and never put them in browser or mobile app code.

Step 2: Get the ID of the team you want

Call List teams to get each team’s name and teamId. Store the ID so your onboarding code can place users on the right team.

Step 3: Invite users with a team, role and metadata

Send a list of users to the create endpoint, and we email each one an invitation. Each person verifies their email address, then sets a password.

Field Required What it does
EmailId Yes The user’s email address, which works well as your unique key
TeamId Yes The team the user joins
UserRole Yes Admin, TeamAdmin or Member
MetaData No Up to 50 key-value pairs, such as department or job title

The Create users reference lists every field. The response returns a userId for each email address, so save it next to your own user record.

curl -X POST \
  'https://api.boldsign.com/v1/users/create' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "EmailId": "alex@example.com",
    "TeamId": "xxc5b097-xxxx-xxxx-xxxx-afd07c66xxxx",
    "UserRole": "Admin",
    "MetaData": {
      "Employee": "Permanent",
      "Department": "Sales",
      "Designation": "Sales Manager"
    }
  },
  {
    "EmailId": "sam@example.com",
    "TeamId": "xxc5b097-xxxx-xxxx-xxxx-afd07c66xxxx",
    "UserRole": "Member",
    "MetaData": {
      "Employee": "Contract",
      "Department": "Sales",
      "Designation": "Sales Executive"
    }
  }
]'
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");
var userClient = new UserClient(apiClient);
var createUserRequest = new List<CreateUserRequest>()
{
    new CreateUserRequest()
    {
        EmailId = "alex@example.com",
        TeamId = "YOUR_TEAM_ID",
        UserRole = UserRoleType.TeamAdmin,
        MetaData = new Dictionary<string, string>()
        {
            { "Employee", "Permanent" },
            { "Department", "Sales" },
            { "Designation", "Sales Manager" }
        }
    },
};
var userCreated = userClient.CreateUser(createUserRequest);
import boldsign

configuration = boldsign.Configuration(api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:

    user_api = boldsign.UserApi(api_client)

    create_user_request = boldsign.CreateUser(
        emailId="alex@example.com", teamId="YOUR_TEAM_ID", userRole="Admin"
    )

    user_created = user_api.create_user([create_user_request])
<?php require_once "vendor/autoload.php";
use BoldSign\Configuration;
use BoldSign\Api\UserApi;
use BoldSign\Model\CreateUser;

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');

$user_api = new UserApi($config);

$create_user_request = new CreateUser();
$create_user_request->setEmailId('alex@example.com');
$create_user_request->setTeamId('YOUR_TEAM_ID');
$create_user_request->setUserRole('Member');

$user_created = $user_api->createUser([$create_user_request]);
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

UserApi userApi = new UserApi(client);

CreateUser createUserRequest = new CreateUser();
createUserRequest.setEmailId("alex@example.com");
createUserRequest.setTeamId("YOUR_TEAM_ID");
createUserRequest.setUserRole(CreateUser.UserRoleEnum.MEMBER);

userApi.createUser(Arrays.asList(createUserRequest));
import { UserApi, CreateUser } from "boldsign";

const userApi = new UserApi();
userApi.setApiKey("YOUR_API_KEY");

var createUserRequest = new CreateUser();
createUserRequest.emailId = "alex@example.com";
createUserRequest.teamId = "YOUR_TEAM_ID";
createUserRequest.userRole = CreateUser.UserRoleEnum.Member;

const userCreated = userApi.createUser([createUserRequest]);

Step 4: List users to check provisioning

List users after the invites go out to confirm each person exists. Use page and pageSize to step through the results, and search to find someone by keyword.

Parameter Required What it does
page Yes The page number to return
pageSize No Users per page, from 1 to 100, with 10 as the default
search No Returns users that match a keyword
curl -X 'GET' \
  'https://api.boldsign.com/v1/users/list?pageSize=10&page=1&search=xxxx' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {your API key}'
var apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key");

var userClient = new UserClient(apiClient);

var userRecords = userClient.ListUsers(1, 10, "alex");
import boldsign

configuration = boldsign.Configuration(api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:

    user_api = boldsign.UserApi(api_client)
    user_records = user_api.list_users(page=1, page_size=10, search="alex")
<?php require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\UserApi;

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');

$user_api = new UserApi($config);
$user_records = $user_api->listUsers($page = 1,$page_Size=10,$search='alex');
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

UserApi userApi = new UserApi(client);

UserRecords userRecords = userApi.listUsers(1, 10, "alex");
import { UserApi } from "boldsign";

const userApi = new UserApi();
userApi.setApiKey("YOUR_API_KEY");
const userRecords = userApi.listUsers(1, 10, "alex");

Each user in the response includes a userId, email, name, team, role and userStatus. You also get created and modified dates and any metadata.

Step 5: Get one user’s details

Call the get endpoint with a stored userId to read that user’s latest status, role, team and metadata. The call works even before the user accepts the invite.

curl -X 'GET' \
  'https://api.boldsign.com/v1/users/get?userId=e892ea92-xxxx-xxxx-xxxx-bbdbcaa5xxxx' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {your API key}'
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");

var userClient = new UserClient(apiClient);

var userDetails = userClient.GetUserDetails("YOUR_USER_ID");
import boldsign

configuration = boldsign.Configuration(api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:

    user_api = boldsign.UserApi(api_client)
    user_details = user_api.get_user(user_id="YOUR_USER_ID")
<?php require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\UserApi;

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');

$user_api = new UserApi($config);
$user_details = $user_api->getUser($user_id='YOUR_USER_ID');
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

UserApi userApi = new UserApi(client);
UserProperties userDetails = userApi.getUser("YOUR_USER_ID");
import { UserApi } from "boldsign";

const userApi = new UserApi();
userApi.setApiKey("YOUR_API_KEY");

const userDetails = userApi.getUser("YOUR_USER_ID");

Read before you write. Fetch the current values before you change a role or team, so you never overwrite a change someone else made.

Step 6: Update a user’s role

Send the UserId and the new UserRole to the update endpoint. Use it to promote a Member to Admin, or to move someone back.

curl -X 'PUT' \
  'https://api.boldsign.com/v1/users/update' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}' \
  -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
  -d '{
  "UserId": "77f0a721-xxxx-xxxx-xxxx-17fcb032xxxx",
  "UserRole": "Admin"
}'
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");
var userClient = new UserClient(apiClient);

var updateUser = new UpdateUser("YOUR_USER_ID", UserRoleType.Admin);

userClient.UpdateUser(updateUser);
import boldsign
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")
with boldsign.ApiClient(configuration) as api_client:
    user_api = boldsign.UserApi(api_client)
    update_User = boldsign.UpdateUser(userId="YOUR_USER_ID", userRole="Admin")
    user_api.update_user(update_User)
<?php require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\UserApi;
use BoldSign\Model\UpdateUser;

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');

$user_api = new UserApi($config);

$update_user = new UpdateUser();
$update_user->setUserId('YOUR_USER_ID');
$update_user->setUserRole('Admin');

$user_api->updateUser($update_user);
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

UserApi userApi = new UserApi(client);

UpdateUser updateUser = new UpdateUser();
updateUser.setUserId("YOUR_USER_ID");
updateUser.setUserRole(UpdateUser.UserRoleEnum.TEAM_ADMIN);

userApi.updateUser(updateUser);
import { UserApi, UpdateUser } from "boldsign";

const userApi = new UserApi();
userApi.setApiKey("YOUR_API_KEY");

const updateUser = new UpdateUser();
updateUser.userId = "YOUR_USER_ID";
updateUser.userRole = UpdateUser.UserRoleEnum.Member;

userApi.updateUser(updateUser);

Step 7: Resend a pending invitation

Resend the invitation email when a user has not acted on the first one. The resend invitation reference shows the full request.

curl -X 'POST' \
  'https://api.boldsign.com/v1/users/resendInvitation?userId=e892ea92-xxxx-xxxx-xxxx-bbdbcaa5xxxx' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}'
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");
var userClient = new UserClient(apiClient);

userClient.ResendInvitation("YOUR_USER_ID");
import boldsign

configuration = boldsign.Configuration(api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:

    user_api = boldsign.UserApi(api_client)
    user_api.resend_invitation(user_id="YOUR_USER_ID")
<?php require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\UserApi;

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');

$user_api = new UserApi($config);
$user_api->resendInvitation($user_id='YOUR_USER_ID');
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

UserApi userApi = new UserApi(client);
userApi.resendInvitation("YOUR_USER_ID");
import { UserApi } from "boldsign";

const userApi = new UserApi();
userApi.setApiKey("YOUR_API_KEY");

userApi.resendInvitation("YOUR_USER_ID");

Step 8: Cancel a pending invitation

Cancel the invitation when someone should no longer join, such as a new hire who changed plans. Both resend and cancel work only for users who have yet to accept.

curl -X 'POST' \
  'https://api.boldsign.com/v1/users/cancelInvitation?userId=e892ea92-xxxx-xxxx-xxxx-bbdbcaa5xxxx' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {your API key}'
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");
var userClient = new UserClient(apiClient);

userClient.CancelInvitation("YOUR_USER_ID");
import boldsign

configuration = boldsign.Configuration(api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:

    user_api = boldsign.UserApi(api_client)
    user_api.cancel_invitation(user_id="YOUR_USER_ID")
<?php require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\UserApi;

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');

$user_api = new UserApi($config);
$user_api->cancelInvitation($user_id='YOUR_USER_ID');
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

UserApi userApi = new UserApi(client);
userApi.cancelInvitation("YOUR_USER_ID");
import { UserApi } from "boldsign";

const userApi = new UserApi();
userApi.setApiKey("YOUR_API_KEY");

userApi.cancelInvitation("YOUR_USER_ID");

How do you update user metadata?

Send the UserId and the keys you want to set to the metadata endpoint. The update is always partial, so keys you leave out keep their current values.

Metadata holds up to 50 key-value pairs per user. Each key can be up to 50 characters, and each value up to 500. Every key also shows up as its own column in the document transaction CSV export.

The update metadata reference has the full request.

curl -X PUT \
  'https://api.boldsign.com/v1-beta/users/updateMetaData' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {apikey}' \
  -H 'Content-Type: application/json' \
  -d '{
  "UserId": "6e455aa5-xxx-xxxx-xxx-2c6590521811",
  "MetaData": {
    "Department": "Sales"
  }
}'
var apiClient = new ApiClient("https://api.boldsign.com", "{apikey}");
var userClient = new UserClient(apiClient);

var updateUserMetaData = new UpdateUserMetaData()
{
    UserId = "6e455aa5-xxx-xxxx-xxx-2c6590521811",
    MetaData = new Dictionary<string, string>()
    {
        ["Department"] = "Sales",
    },
};

await userClient.UpdateUsersMetaDataAsync(updateUserMetaData);
import boldsign

# Configure the BoldSign client
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:

    # Initialize the Users API
    users_api = boldsign.UsersApi(api_client)

    # Prepare the metadata update request
    update_request = boldsign.UpdateUserMetaData(
        user_id="6e455aa5-xxx-xxxx-xxx-2c6590521811", meta_data={"Department": "Sales"}
    )

    # Call the API to update metadata
    users_api.update_users_meta_data(update_request)
<?php require_once "vendor/autoload.php";
use BoldSign\Configuration;
use BoldSign\Api\UsersApi;
use BoldSign\Model\UpdateUserMetaData;

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');

$users_api = new UsersApi($config);

$update_meta = new UpdateUserMetaData();
$update_meta->setUserId('YOUR_USER_ID');
$update_meta->setMetaData([
    'Department' => 'Sales',
]);

$users_api->updateUsersMetaData($update_meta);
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

UsersApi usersApi = new UsersApi(client);

// Prepare metadata update request
UpdateUserMetaData updateMeta = new UpdateUserMetaData();
updateMeta.setUserId("YOUR_USER_ID");

Map<String, String> metaData = new HashMap<>();
metaData.put("Department", "Sales");

updateMeta.setMetaData(metaData);

usersApi.updateUsersMetaData(updateMeta);
import { UsersApi, UpdateUserMetaData } from "boldsign";

// Initialize the Users API
const usersApi = new UsersApi();
usersApi.setApiKey("YOUR_API_KEY");

// Prepare the metadata update request
const updateMetaDataRequest = new UpdateUserMetaData();
updateMetaDataRequest.userId = "6e455aa5-xxx-xxxx-xxx-2c6590521811"; // User ID
updateMetaDataRequest.metaData = {
  Department: "Sales",
};

// Call the API to update metadata
usersApi.updateUsersMetaData(updateMetaDataRequest);

How do you move a user to another team?

Call the change team endpoint with the user’s ID and the new team’s ID. You can also name a second user to take over the moved user’s documents.

Parameter Where it goes Required What it does
userId Query Yes The user you are moving
toTeamId Request body Yes The team the user moves to
transferDocumentsToUserId Request body No The user who receives the moved user’s documents

The change team reference shows each option.

curl --location --request PUT \
  'https://api.boldsign.com/v1/users/changeTeam?userId=d98c14c5-xxx-xxxx-xxx-b39ca83c0da8' \
  --header 'accept: */*' \
  --header 'X-API-KEY: {apikey}' \
  --header 'Content-Type: application/json' \
  --data '{
  "toTeamId": "9bca0986-xxx-xxxx-xxx-30ffe3a2c5b7"
}'
var apiClient = new ApiClient("https://api.boldsign.com", "{apikey}");
var userClient = new UserClient(apiClient);

var changeTeam = new ChangeTeam()
{
    ToTeamId = "9bca0986-xxx-xxxx-xxx-30ffe3a2c5b7"
};

userClient.ChangeTeam("UserId", changeTeam);
import boldsign

configuration = boldsign.Configuration(api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:

    # Initialize the User API
    user_api = boldsign.UserApi(api_client)

    # Prepare the change team request
    change_team_request = boldsign.ChangeTeamRequest(
        to_team_id="9bca0986-xxx-xxxx-xxx-30ffe3a2c5b7"
    )

    response = user_api.change_team(
        user_id="6e455aa5-xxx-xxxx-xxx-2c6590521811", change_team_request=change_team_request
    )
<?php
require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\UserApi;
use BoldSign\Model\ChangeTeamRequest;

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');

$user_api = new UserApi($config);

$change_team = new ChangeTeamRequest();
$change_team->setToTeamId('YOUR_TEAM_ID');

$response = $user_api->changeTeam('YOUR_USER_ID', $change_team);
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

UserApi userApi = new UserApi(client);

// Prepare change team request
ChangeTeamRequest changeTeam = new ChangeTeamRequest();
changeTeam.setToTeamId("YOUR_TEAM_ID");

// Call the API to change team for the user
userApi.changeTeam("YOUR_USER_ID", changeTeam);
import { UserApi, ChangeTeamRequest } from "boldsign";

const userApi = new UserApi();
userApi.setApiKey("YOUR_API_KEY");

const changeTeamRequest = new ChangeTeamRequest();
changeTeamRequest.toTeamId = "9bca0986-xxx-xxxx-xxx-30ffe3a2c5b7";

userApi.changeTeam("6e455aa5-xxx-xxxx-xxx-2c6590521811", changeTeamRequest);

What happens to documents when a user changes team?

A team move has side effects, so plan for them before you run one in production.

  • Documents still in progress are declined or revoked.
  • Every sender identity approval for the moved user is revoked.
  • The new owner must ask those sender identities for approval again to reach on-behalf documents.

Our guide to OAuth and sender identities explains how on-behalf sending works.

What are good practices for user provisioning in production?

Keep credentials safe and make every call safe to repeat. These habits prevent most provisioning problems.

  • Keep API keys and OAuth tokens on your server only.
  • Treat email as your unique key, and store the BoldSign userId next to it.
  • Retry failed calls with growing waits between attempts.
  • Fetch a user’s current role, team and status before you change them.
  • Test team moves in the sandbox before you run them on live users.

Which BoldSign plan do you need for the Users API?

Every BoldSign plan, including the free one, includes sandbox API access for testing. Live API calls need the Enterprise API plan, from $30 a month with 40 envelopes, billed yearly.

The Enterprise API plan includes 2 users, and each extra envelope costs $0.75. The number of users you can invite depends on your plan. Prices are in USD, as of November 2026, and the pricing page lists every plan.

How do you start managing users with the BoldSign API?

Start in the sandbox, then build your onboarding flow one step at a time. Here are three next steps.

Frequently asked questions

How do I invite users with the BoldSign Users API?

Send a list of users to the create users endpoint. Give each one an email address, a team ID and a role, plus optional metadata.

How do I find the userId for later calls?

The create call returns a userId for each email address. You can also call the List users endpoint and search by keyword.

Which roles can I give a user through the API?

You can give a user the Admin, TeamAdmin or Member role. Set the role when you invite the user, then change it later with the update endpoint.

When can I resend or cancel a user invitation?

Only while the invitation is still pending. Once a user accepts the invite, both endpoints stop applying to that user.

Does updating user metadata overwrite existing values?

No. The metadata update is always partial: keys you send are added or changed, and keys you leave out stay as they are.

Can I move a user to another team with the API?

Yes. The change team endpoint moves a user to a new team. You can also pass a second user ID to take over the moved user's documents.

Can users from another organization be invited?

No. A person who already belongs to another BoldSign organization cannot be invited to yours. The number of users you can invite also depends on your plan.

Can I test the Users API for free?

Yes. A free API sandbox account lets you call the Users API with a sandbox key before you move to a live plan.

Ranjitha Vazhivittan

Ranjitha is a skilled software developer with 3 years of experience at BoldSign. Alongside her technical expertise, she has a passion for writing and enjoys sharing thoughtful insights on technology and development. Beyond work, she stays curious by exploring emerging tools and trends, constantly seeking opportunities to learn and grow.

More posts by Ranjitha Vazhivittan
Get started

Sign up for your free trial today!

Start free trial
  • 30-day free trial
  • No credit card required