Sales Team Management integration guide
Learn how to configure Sales Team Management via API.
This feature is currently in beta, and we're working to improve it. If you have any questions, please contact our Support.
Sales Team Management allows you to organize your sales force into a hierarchical structure using Organization Units (OUs). Each unit can contain users and B2B contracts, giving you control over which commercial conditions are available to each team.
This guide covers the API operations needed to configure and operate Sales Team Management programmatically: creating the unit hierarchy, assigning users, and linking B2B contracts.
All requests require a
VtexIdclientAutCookieauthentication header. See Authentication for details.
Data model overview
Sales Team Management is built around three core entities:
- Organization Unit (OU): A node in the sales team hierarchy. Every unit must have the
typefield set toSales Team. New units are always created at the root level and can later be moved to become child units of another unit. - User: A VTEX account user assigned to an organization unit. Users inherit the contracts linked to their unit.
- Contract: A B2B contract (stored in Master Data) linked to an organization unit via the
contractIdsscope. All users in the unit gain access to the contracts linked to it.
Setup flow
Follow this sequence when setting up Sales Team Management for the first time:
- Create the units you need using Create organization unit. Every unit is created at the root level.
- Build the hierarchy by moving units under their parent with Move organization unit, passing the parent unit's ID as
parentId. Units that should stay at the top of the hierarchy don't need to be moved. - Add users to each unit using Add user to organization unit.
- Link B2B contracts to the appropriate units using Create organization unit scope.
- Verify the hierarchy using Get all children organization units and Get root organization units.
- Verify linked contracts using Get organization unit scopes.
- Verify users and their accessible scopes using List users from organization unit and Get user scopes.
Organization unit management
Use the Organization Units API to create and manage the sales team hierarchy:
| Method | Endpoint | Description |
|---|---|---|
GET | Get root organization units | Returns all top-level units (no parent). |
GET | Search organization units | Lists all units with pagination. Always set type=Sales Team. |
GET | Get organization unit | Returns the full details of a unit by ID. |
POST | Create organization unit | Creates a unit at the root level. You must include in the request body the type parameter and set it to Sales Team. This endpoint always creates root units; to make a unit a child of another, move it afterward with Move organization unit. |
PATCH | Rename organization unit | Updates the unit name without changing its position in the hierarchy. |
PUT | Move organization unit | Moves a unit under a new parent by passing the target parent's ID as parentId in the request body. This is how you turn a root unit into a child unit. All child units move with it. Omit parentId or send parentId: null to promote the unit back to the root level. |
DELETE | Delete organization unit | Permanently deletes a unit. This action can’t be undone. Before proceeding, confirm the unit has no linked users or child units. |
User management
Use the Organization Units API to assign users to units and check their access:
| Method | Endpoint | Description |
|---|---|---|
GET | List users from organization unit | Returns all users in a unit, including IDs, emails, and roles. |
POST | Add user to organization unit | Adds one or more users to a unit. Users must already exist in the VTEX account. |
DELETE | Remove users from organization unit | Removes users from a unit without deleting them from the account. Requires a request body with userIds. |
GET | Get user's organization unit | Returns the unit to which a user belongs. |
GET | Get user scopes | Returns all scopes (contracts and resources) accessible to a user through their unit. Scopes can be inherited from parent units. |
To retrieve user details and roles, use the License Manager API:
GETGet admin user information by user ID: Returns user data by ID.GETGet roles by admin user ID or API Key: Returns user data and associated roles.
Contract management
B2B contracts are stored in Master Data and linked to organization units via the contractIds scope. All users in a unit gain access to the contracts linked to it. Use the Organization Units API to manage contract associations:
| Method | Endpoint | Description |
|---|---|---|
GET | Get organization unit scopes | Returns all scopes linked to a unit. Contracts are identified by "scope": "contractIds". |
POST | Create organization unit scope | Links one or more contracts to a unit. Use contractIds as the scope parameter. Accepts multiple IDs in a single request. |
DELETE | Delete organization unit scope | Removes one or more contracts from a unit. Users in the unit lose access to those contracts. |
To retrieve full contract details, use the Master Data API v2 with dataEntityName=CL.
Organizational structure
Use Get all children organization units to traverse the hierarchy below a given unit. The shallowSearch parameter controls the depth:
shallowSearch=true: Returns direct children only.shallowSearch=false(default): Returns the full subtree recursively. May be slower for large hierarchies.