--- title: "List the candidates eligible to be selected as an upline for a contract-assignment" url: "https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16/operations/listAvailableUplinesForContractAssignmentV2" --- > 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 contract-assignment `GET` `/v2/contract-assignments/{id}/available-uplines` Operation ID: `listAvailableUplinesForContractAssignmentV2` Returns the contract-assignment changes eligible to be selected as an upline for a new change on the given contract-assignment over the supplied date range, as a token-paginated collection. Candidates share the assignment's product and overlap the `start_date`/`end_date` window. Results are scoped to the caller's organization(s). ## Path parameters - `id` (string, uuid, required) - The contract-assignment to find available uplines for. ## Query parameters - `start_date` (string, date, required) - Start of the prospective change's commission-terms window. Candidates whose window is still open on or after this date are included. - `end_date` (string, date, optional) - End of the prospective change's commission-terms window. When provided, candidates whose window starts after this date are excluded. - `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). ## Responses - `200` - A page of available upline candidates. - `400` - Missing or invalid `start_date`, or invalid `end_date`, `page_token`, or `page_size`. - `401` - Missing or invalid bearer token. - `403` - The bearer token is not authorized for this resource. - `404` - The contract-assignment 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/contract-assignments/{id}/available-uplines: get: tags: - Hierarchies operationId: listAvailableUplinesForContractAssignmentV2 summary: List the candidates eligible to be selected as an upline for a contract-assignment description: > Returns the contract-assignment changes eligible to be selected as an upline for a new change on the given contract-assignment over the supplied date range, as a token-paginated collection. Candidates share the assignment's product and overlap the `start_date`/`end_date` window. Results are scoped to the caller's organization(s). security: - oauth2: - contracting.contractassignments.read parameters: - name: id in: path required: true description: The contract-assignment to find available uplines for. schema: type: string format: uuid - name: start_date in: query required: true description: > Start of the prospective change's commission-terms window. Candidates whose window is still open on or after this date are included. schema: type: string format: date example: 2026-01-01 - name: end_date in: query required: false description: > End of the prospective change's commission-terms window. When provided, candidates whose window starts after this date are excluded. schema: type: string format: date example: 2026-12-31 - $ref: "#/components/parameters/PageToken" - $ref: "#/components/parameters/PageSize" responses: "200": description: A page of available upline candidates. content: application/json: schema: $ref: "#/components/schemas/AvailableUplineChangeV2Page" "400": description: Missing or invalid `start_date`, or invalid `end_date`, `page_token`, or `page_size`. 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 contract-assignment 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 schemas: AvailableUplineChangeV2Page: type: object description: A token-paginated page of available upline candidates (plain envelope, no HAL wrappers). properties: items: type: array items: $ref: "#/components/schemas/AvailableUplineChangeV2" 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 AvailableUplineChangeV2: type: object description: > A contract-assignment change eligible to be selected as an upline, scoped to a contract-assignment or contract-assignment-change. properties: contractAssignmentChangeId: type: string format: uuid 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 fromOrganizationId: type: string format: uuid npn: type: string writingNumber: type: string levelOfCommission: type: number annualizationProportion: type: number productId: type: string format: uuid testAccount: type: boolean startDate: type: string format: date endDate: type: string format: date commissionLevelName: type: string contractAssignmentChangeDisplayNumber: type: string required: - contractAssignmentChangeId 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. ```