Request

Response

    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:

    FieldWhat 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 unlimited is true, totalQuantity and assignedQuantity are both null. Don’t compute free seats for an unlimited pool.
    • Future-dated pools: the operation also returns pools that haven’t started yet, and assignedQuantity can be null for them. Don’t read null as zero. Compare startDate and endDate with today’s date to see whether the pool is usable now.
    • Limited pools: when both counts are present, the free seats are totalQuantity minus assignedQuantity. A pool with no free seats can’t take another assignment, and the request is rejected with a 422 status 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 typeWhat 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:

    StatusWhat 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:

    StatusWhat 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