Product Pools and Assignments
This topic explains how product pools and assignments behave, so you can predict what a request returns before you send it. API Basics introduces both ideas. This topic covers the details.
Choose a product pool
A product pool is the set of seats that a team has for a product. To assign a product, you need its productId, and you get it from a List Product Pools response. The ID must come from that operation. Don’t use an ID from any other source.
The operation returns only the supported pools whose seats you can assign to users. It omits hidden and unsupported pools. Assigning or unassigning a known unsupported pool is rejected with a 422 status code.
Read seat counts
Each pool reports its seats with these fields:
| Field | What it tells you |
|---|---|
totalQuantity |
The number of seats in the pool. |
assignedQuantity |
The number of seats that are assigned. |
unlimited |
Whether the pool has an unlimited number of seats. |
startDate and endDate |
The dates between which the pool is usable. |
Before you assign a product, check these cases:
- Unlimited pools: when
unlimitedistrue,totalQuantityandassignedQuantityare bothnull. Don’t compute free seats for an unlimited pool. - Future-dated pools: the operation also returns pools that haven’t started yet, and
assignedQuantitycan benullfor them. Don’t readnullas zero. ComparestartDateandendDatewith today’s date to see whether the pool is usable now. - Limited pools: when both counts are present, the free seats are
totalQuantityminusassignedQuantity. A pool with no free seats can’t take another assignment, and the request is rejected with a422status code. - Seat counts change: other administrators can assign seats between your read and your request. Treat the counts as a guide, and check the response to your request.
How assignments work
Once you have chosen a pool, you can assign its seats to users. An assignment gives a user access to a product, using a seat from a product pool. Each user and product pair appears once in a List Assignments response. Its assignmentType field shows how the user holds the product.
Direct and inherited assignments
| Assignment type | What it means |
|---|---|
TEAM |
The user inherits the product from an assignment made to the whole team. |
DIRECT |
The product is assigned directly to the user. |
GROUP |
The user inherits the product through a group. |
When a user holds the same product in more than one way, assignmentType shows the first match in the order TEAM, DIRECT, GROUP. It identifies the effective assignment.
The List Assignments operation returns direct assignments and inherited assignments. You can create and remove DIRECT assignments only. You can’t create or remove TEAM or GROUP assignments through the API.
Assign a product
The Assign Product operation gives a user a seat from a pool. It is safe to repeat: creating an assignment that already exists leaves the team in the same state, and the response contains the current assignment. Use the status code to see what happened:
| Status | What happened |
|---|---|
201 |
The assignment is new. |
200 |
The assignment already existed. Nothing changed. |
404 |
The resource wasn't found, or isn't visible to you. |
422 |
The request can't be applied, for example because the pool has no seats available or isn't supported. |
Because the operation is safe to repeat, you can send the request again if it times out. For how to handle a timeout or a 5xx response, see Retry a write safely.
Unassign a product
The Unassign Product operation removes a direct assignment and releases its seat. It takes no request body. Use the status code to see what happened:
| Status | What happened |
|---|---|
204 |
The direct assignment was removed. |
404 |
The resource wasn't found, or isn't visible to you. This includes a user with no direct or inherited assignment for the product, and a repeat of a successful deletion. |
422 |
The request can't be applied, for example because only inherited assignments remain, or the pool isn't supported. |
Removing a direct assignment keeps any inherited assignment. A user can still hold the product through the team or a group after you remove the direct assignment.
If you repeat the request after a successful removal and inherited access remains, the repeat is rejected with 422.
Read assignments
The List Assignments operation returns every matching assignment in one response, with no pagination. You can narrow the results with two optional filters:
productId: only assignments for that product.userId: only assignments held by that user. A user who isn’t on the team has no assignments in the response.
Assignments to hidden or unsupported products are omitted. A filter for an unsupported product returns an empty list.
Changes can appear in team-wide results after a delay, and a filtered list might also lag. To confirm a change that you just made, rely on the response to your Assign Product or Unassign Product request.
See also
- Assign a Product to a User — Follow the walkthrough from finding a user to removing an assignment.
- Pagination — Learn how to retrieve every page of the product pool list.
- Error Handling — Learn how to read and react to
404,422, and other error responses. - REST API Reference — Look up the request and response of each operation.