Create and Manage Users Easily with BoldSign API

TL;DR: The BoldSign Users API enables end-to-end automated user management by allowing applications to invite users, assign roles and teams, manage invitations, update user details, and audit users programmatically, removing the need for manual administration.

If you want to automate user onboarding and access control in BoldSign, you can do it end-to-end with the BoldSign Users API: invite users, assign roles, list and fetch user details for auditing, update roles, and resend or cancel invitations. 

This guide is for developers embedding eSignatures into an app who need consistent, programmatic user provisioning instead of manual admin work. 

What you can automate with the BoldSign Users API

• Provision users during onboarding (bulk invite by email) 
• Assign teams and roles (Admin/Member/ TeamAdmin) 
• Track and audit user rosters (list users + get user details) 
• Manage invitation state (resend/cancel for pending users) 
• Optionally manage organization changes (metadata updates, team moves) 

What you’ll need before you start

• A  BoldSign account(sandbox or production). 
• An API key(orOAuth2 access token) to call BoldSign APIs over HTTPS. 
• A REST client such as cURL, Postman, or your preferred HTTP library. 

Authentication headers should be in one of the following formats: 

• API Key: X-API-KEY:  
• OAuth2: Authorization: Bearer  

Note: The examples below use API key authentication for clarity. 

BoldSign Users API endpoints used in this guide 

Core users endpoints (v1) 

Task	Method	Endpoint
Invite users (create users)	POST	https://api.boldsign.com/v1/users/create
List users	GET	https://api.boldsign.com/v1/users/list
Get a user	GET	https://api.boldsign.com/v1/users/get
Update user role	PUT	https://api.boldsign.com/v1/users/update
Resend invitation	POST	https://api.boldsign.com/v1/users/resendInvitation
Cancel invitation	POST	https://api.boldsign.com/v1/users/cancelInvitation
Update user metadata	PUT	https://api.boldsign.com/v1/users/updateMetaData
Move user to another team	PUT	https://api.boldsign.com/v1/users/changeTeam

How to auto-provision users during app onboarding

If your SaaS product maps each customer to a BoldSign organization, your onboarding flow typically needs to: 

• Assign users to the right team 
• Set the correct role (Admin/Member/TeamAdmin) 
• Attach department metadata (for reporting) 
• Handle invitations (resend/cancel) 
• Keep the roster auditable via API 

The rest of this document implements that flow step-by-step. 

How to create and manage BoldSign users

Step 1: Authenticate your requests 

For each request, include any one of the following: 

• API Key (server-to-server): X-API-KEY:  
• OAuth2 (delegated): Authorization: Bearer  

Pro tip: Keep API keys and OAuth tokens server-side only—never embed them in browser/mobile apps. 

Step 2: Get the Team ID you want to assign users to

Before inviting users, list teams and pick the right teamId. 

You can find detailed instructions in the Teams API documentation. 

What this does: Fetches teams (including teamId) so you can place users into the correct team. 

Note: teamId is not mandatory when creating a user. If you want to assign the user to a team, include the teamId; otherwise, you can skip this step.

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

Creating users is an invite flow: you send email addresses and BoldSign emails the invite. Users complete verification and set a password. 

Required fields for invitations 

Field	Required	What it’s for	Notes
EmailId	Yes	User’s email (treat this as your natural unique key)	Use a valid email format
TeamId	No	Which BoldSign team the user belongs to	Get from /v1/teams/list
UserRole	No	Admin or Member or TeamAdmin	Set explicitly for predictable access
MetaData	No	Key-value attributes (department, designation, etc.)	Useful for reporting and filters

For more details, refer to the official Create User API documentation

 

    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": "[e-mail]", 
            "TeamId": "xxc5b097-xxxx-xxxx-xxxx-afd07c66xxxx", 
            "UserRole": "Admin", 
            "MetaData": { 
                "Employee": "Permanent", 
                "Department": "Sales", 
                "Designation": "Sales Manager" 
            } 
        }, 
        { 
            "EmailId": "[e-mail]", 
            "TeamId": "xxc5b097-xxxx-xxxx-xxxx-afd07c66xxxx", 
            "UserRole": "Member", 
            "MetaData": { 
                "Employee": "Contract", 
                "Department": "Sales", 
                "Designation": "Sales Executive" 
            } 
        } 
    ]'

Step 4: List users to verify provisioning

After invites are sent, list users to confirm they exist and capture userId for future actions. 

For more details, see the official List Users API documentation 

Which query parameters control pagination and search? 

Parameter	Required?	What it does	Notes
page	No	Page number to fetch	Typically starts from 1
pageSize	No	Number of users per page	Defaults to 10; can be set between 1 and 100
search	No	Filter results by user attributes (e.g., username, email, userId)	Useful for quick lookups

    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}' 

Step 5: **Get a single user’s details**

Use users/get when you have a stored userId and want the latest status, role, teamId, and metadata. 

Check the official Get User API documentation for complete usage guidelines.

 

    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}' \ 

Pro tip: Read before your right. Fetch current values before you update roles or team assignment to avoid accidental overwrites. 

Step 6: Update a user’s role

Promote a user to Admin (or demote back to Member) using the update endpoint. 

Refer to the official Update User API documentation for detailed information and examples.

 

    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" 
    }' 

What this does: Updates the role of a specified user in your BoldSign organization. 

Step 7: Resend or cancel invitations

If a user hasn’t accepted their invitation yet, you can resend or cancel it. 

Resend invitation 

Refer to the official Resend invitations guide for detailed steps and best practices.

 

    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}'  

Cancel invitation 

For detailed instructions, see the cancel invitations guide.

 

    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}' 

Edge case: Resend/cancel applies only to users who haven’t accepted the invite. 

How to update user metadata

If you store extra information like department or employee type, the endpoint supports partial updates. 

 For detailed guidance, see the official Update user metadata documentation

 

    curl -X PUT 'https://api.boldsign.com/v1/users/updateMetaData' \ 
    -H 'accept: */*' \ 
    -H 'X-API-KEY: {apikey}' \ 
    -H 'Content-Type: application/json' \ 
    -d '{ 
      "UserId": "6e455aa5-xxx-xxxx-xxx-2c6590521811", 
      "MetaData": { 
        "Department": "Sales" 
      } 
    }'  

How to move a user to another team

When a user changes departments, move them to a different team. The change-team endpoint can optionally transfer documents. 

Parameter	Type	Required	Description
userId (Query)	string	Yes	The unique identifier of the user being moved. Obtainable from the Users or Teams section of the web app.
toTeamId (Request Body)	string	Yes	The target team ID to which the user will be transferred.
transferDocumentsToUserId (Request Body)	string	No	The user ID of the recipient who will inherit the documents of the transferred user.

 

Consult the official Change team API documentation  for comprehensive guidance and best practices.

 

    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"}'   

What this does: Moves a user to a new team and optionally transfers their documents. 

Plan ahead for: document ownership, in-progress workflows, and approval side effects. 

Important Notes 

• In-progress documents: If a document is currently in-progress, it will be declined or revoked during transfer. 
• Completed documents: All completed documents will remain in the completed state and are moved along with the user when they change to another team. 
• Sender identity approvals: All sender identity approvals associated with the changed user will be revoked. The reassigned user must obtain approval again from those sender identities to access on-behalf documents. 
• Impact & Risks: 
  • Transferred documents become accessible under the new team, which may alter visibility and permissions. 
  • Sensitive or confidential files could unintentionally be exposed to new team members. 
  • TransferDocumentsToUserId behavior*:* If specified, all transferred documents will be accessible only to the new target user. The old user will no longer have access once the transfer is complete. 

Testing checklist for a reliable onboarding flow 

1. List teams → pick a teamId. 
2. Create (invite) user(s) → confirm invitation sent. 
3. List users → capture userId. 
4. Get user → verify userStatus, role, teamId, metadata. 
5. Update role or resend/cancel invite as needed. 
6. Optional: update metadata or change team. 

Best practices for production-grade provisioning 

• Never expose credentials client-side. Keep API keys/OAuth tokens on the server. 
• Avoid duplicate provisioning. Treat email as your unique key, and store a mapping to BoldSign userId. 
• Implement retries with exponential backoff for transient failures. 
• Read before you write. Fetch current role/team/status before applying updates. 
• Validate behavior and plan for change. 

Key takeaways

With the BoldSign Users API, you can run a complete provisioning lifecycle inside your product: invite in bulk, audit users, update roles, and manage invitations. For richer admin workflows, endpoints like metadata updates and team moves help model real org changes, just plan carefully around document ownership and workflow side effects. 

Take advantage of a 30-day free trial, or get expert assistance via the BoldSign support portal to design your ideal integration. 

Related blogs

• Async API Architecture: Using Queues to Scale REST and gRPC Services
• BoldSign Webhooks: App vs Account—How to Choose
• API Key Vs. OAuth – How to Choose the best Authentication

Note: This blog was originally published at boldsign.com