--- title: "HierarchyNodeV2Page" url: "https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16/schemas/HierarchyNodeV2Page" --- > Full API specification: https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16.md # HierarchyNodeV2Page A token-paginated page of hierarchy nodes (plain envelope, no HAL wrappers). ## 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 components: schemas: HierarchyNodeV2: type: object description: > A node in an organization's contract-assignment hierarchy, decoupled from the internal Contracting domain models. The node key is `contractAssignmentId`; `uplineContractAssignmentId` links to the parent node and is null on root nodes. Reference names are inlined next to their ids. `active` is computed over the tree — a node is inactive when its own status is inactive or any node above it is. A node represents either an individual (`type` = `AGENT`, identified by `personId`) or a firm (`type` = `FIRM`, identified by `firmId`); the identifier that does not apply to the node's kind is null. properties: contractAssignmentId: type: string format: uuid description: The node's key — the stable identity of a producer's placement for a product. uplineContractAssignmentId: type: string format: uuid description: The parent node's contractAssignmentId, or null for root nodes. producerName: type: string description: The producer or organization at this position. type: type: - string - "null" description: > The producer kind at this position. Null when the position identifies neither an individual nor a firm. enum: - AGENT - FIRM - null personId: type: string format: uuid description: The individual's id (null for firms). firmId: type: string format: uuid description: The firm's id (null for individuals). npn: type: string description: National Producer Number of the individual or firm at this position. productId: type: string format: uuid productName: type: string description: The product name (inlined so no follow-up lookup is needed). carrierOrganizationId: type: string format: uuid description: > The carrier organization the assignment is sent to. Matches the `carrierOrganizationId` reported for the same assignment by the contracts, contract-assignments and contract-assignment-changes endpoints. carrierOrganizationName: type: string description: The carrier organization name (inlined so no follow-up lookup is needed). assignmentStatusId: type: string format: uuid assignmentStatusName: type: string description: The human-readable assignment status (inlined). commissionLevelId: type: string format: uuid commissionLevelName: type: string description: The commission level name (inlined). commissionLevel: type: number description: The commission level's numeric value. stateAbbreviations: type: array items: type: string description: States this position is contracted for. writingNumber: type: string description: Carrier-assigned writing number, if applicable. effectiveOn: type: string format: date description: The assignment's contractual effective date (yyyy-MM-dd). expiresOn: type: string format: date description: The assignment's contractual expiration date (yyyy-MM-dd). active: type: boolean description: Whether this position is active, computed over the tree. partnershipId: type: string format: uuid description: > The partnership holding this contract, when its commission is split across partnership members. Absent on nodes whose contract is held by a single producer. partnershipName: type: string description: The partnership's name (inlined). Absent when the node has no partnership. partnershipActive: type: boolean description: > Whether the partnership is still current. A dissolved partnership is still reported — its splits are what explain an in-force assignment's commission — so use this flag rather than the presence of `commissionSplits` to tell whether the arrangement is active. Always absent when the node has no partnership, and may be absent even when it does if the partnership's state was never recorded; treat absent as unknown rather than as inactive. commissionSplits: type: array items: $ref: "#/components/schemas/CommissionSplitV2" description: > How the commission earned on this node is divided across the partnership's members. Always present; empty on nodes whose contract is not held by a partnership. required: - contractAssignmentId - active - commissionSplits 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 CommissionSplitV2: type: object description: > One partnership member's share of the commission earned on a hierarchy node. Splits are not effective-dated internally, so — unlike the rest of the node — they reflect the partnership's current state rather than the requested `as_of` date. properties: personId: type: string format: uuid description: The member this share belongs to. producerName: type: string description: The member's name (inlined). Partnership members are always individuals. splitPercentage: type: number description: > The member's share as a proportion in `[0, 1]` — a 60/40 split is reported as `0.60` and `0.40`. The shares of a fully-allocated partnership sum to exactly `1`, but this is not guaranteed: only an upper bound of 100% is enforced internally, so a partially allocated partnership's shares sum to less than `1`. example: 0.6 primary: type: boolean description: > Whether this is the partnership's primary partner. Exactly one member is primary, and it is listed first. required: - personId - splitPercentage - primary HierarchyNodeV2Page: type: object description: A token-paginated page of hierarchy nodes (plain envelope, no HAL wrappers). properties: items: type: array items: $ref: "#/components/schemas/HierarchyNodeV2" page: $ref: "#/components/schemas/PageInfo" required: - items - page ```