---
title: "List the candidates eligible to be selected as an upline for a product"
url: "https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16/operations/listAvailableUplinesV2"
---

> Full API specification: https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16.md

# List the candidates eligible to be selected as an upline for a product

`GET` `/v2/products/{productId}/available-uplines`

Operation ID: `listAvailableUplinesV2`

Returns the currently-approved contract assignments eligible to be selected as another contract assignment's upline for the given product, as a token-paginated collection. Results are scoped to the caller's organization(s). Optionally narrowed with `as_of` to candidates whose current commission-terms window covers a given date.

## Path parameters

- `productId` (string, uuid, required) - The product to find available uplines for.

## Query parameters

- `page_token` (string, optional) - Opaque continuation token from a previous response's `page.nextToken`. Omit for the first page.
- `page_size` (integer, optional) - Maximum number of items to return. Defaults to 25; values outside `[1, 250]` are rejected with `400` (not clamped).
- `as_of` (string, date, optional) - Narrow results to candidates whose current commission-terms window covers this date (inclusive). Omit to return all eligible candidates regardless of window.

## Responses

- `200` - A page of available upline candidates.
- `400` - Invalid `page_token`, `page_size`, or `as_of`.
- `401` - Missing or invalid bearer token.
- `403` - The bearer token is not authorized for this resource.
- `404` - The product does not exist or does not belong to the caller's organization.

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: AgentSync Contracting & Hierarchies API
  version: v1.7.6
servers:
  - url: https://api.sandbox.agentsync.io/contracting
    description: Sandbox
  - url: https://api.agentsync.io/contracting
    description: Production
paths:
  /v2/products/{productId}/available-uplines:
    get:
      tags:
        - Hierarchies
      operationId: listAvailableUplinesV2
      summary: List the candidates eligible to be selected as an upline for a product
      description: >
        Returns the currently-approved contract assignments eligible to be
        selected as another

        contract assignment's upline for the given product, as a token-paginated
        collection.

        Results are scoped to the caller's organization(s). Optionally narrowed
        with `as_of` to

        candidates whose current commission-terms window covers a given date.
      security:
        - oauth2:
            - contracting.contractassignments.read
      parameters:
        - name: productId
          in: path
          required: true
          description: The product to find available uplines for.
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/PageToken"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/AsOf"
      responses:
        "200":
          description: A page of available upline candidates.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AvailableUplineV2Page"
        "400":
          description: Invalid `page_token`, `page_size`, or `as_of`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Missing or invalid bearer token.
        "403":
          description: The bearer token is not authorized for this resource.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "404":
          description: The product does not exist or does not belong to the caller's
            organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
security:
  - oauth2:
      - contracting.contractassignments.read
components:
  parameters:
    PageToken:
      name: page_token
      in: query
      required: false
      description: >
        Opaque continuation token from a previous response's `page.nextToken`.
        Omit for the first

        page.
      schema:
        type: string
    PageSize:
      name: page_size
      in: query
      required: false
      description: >
        Maximum number of items to return. Defaults to 25; values outside `[1,
        250]` are rejected

        with `400` (not clamped).
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 25
    AsOf:
      name: as_of
      in: query
      required: false
      description: >
        Narrow results to candidates whose current commission-terms window
        covers this date

        (inclusive). Omit to return all eligible candidates regardless of
        window.
      schema:
        type: string
        format: date
        example: 2026-06-22
  schemas:
    AvailableUplineV2Page:
      type: object
      description: A token-paginated page of available upline candidates (plain
        envelope, no HAL wrappers).
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/AvailableUplineV2"
        page:
          $ref: "#/components/schemas/PageInfo"
      required:
        - items
        - page
    ApiError:
      type: object
      description: The AgentSync error shape.
      properties:
        message:
          type: string
          description: A human-readable description of the error.
        details:
          type: array
          description: Optional field-level details.
          items:
            type: object
            properties:
              param:
                type: string
              message:
                type: string
      required:
        - message
    AvailableUplineV2:
      type: object
      description: A currently-approved contract assignment eligible to be selected as
        an upline.
      properties:
        contractAssignmentId:
          type: string
          format: uuid
        firstName:
          type: string
        lastName:
          type: string
        suffix:
          type: string
        firmId:
          type: string
          format: uuid
        firmName:
          type: string
          description: The candidate's firm name, if the candidate is a firm.
        personId:
          type: string
          format: uuid
        npn:
          type: string
        writingNumber:
          type: string
        levelOfCommission:
          type: number
        annualizationProportion:
          type: number
        productId:
          type: string
          format: uuid
        testAccount:
          type: boolean
        commissionLevelName:
          type: string
      required:
        - contractAssignmentId
    PageInfo:
      type: object
      description: Pagination metadata for a V2 list response.
      properties:
        size:
          type: integer
          description: Number of items returned in this response (equal to items.length).
        nextToken:
          type:
            - string
            - "null"
          description: Opaque continuation token for the next page, or null on the last
            page.
      required:
        - size
        - nextToken
  securitySchemes:
    oauth2:
      type: oauth2
      description: >
        OAuth2 client credentials. The `tokenUrl` below is the SANDBOX token
        endpoint; for production use `https://auth.agentsync.io/oauth2/token`.
        OpenAPI 3.1 permits only one token URL per flow, so both cannot be
        expressed here - see https://developer.agentsync.io/api-authentication
        for the full environment table, how to request credentials, and worked
        token-retrieval examples.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sandbox.agentsync.io/oauth2/token
          scopes:
            contracting.producers.read: Read producers.
            contracting.contracts.read: Read contracts.
            contracting.contractassignments.read: >
              Read contract assignments, assignment changes, assigned carriers,
              products and commission levels, available uplines, responsible
              upline firms, and hierarchies.
```