Hierarchies API Overview

AgentSync's Hierarchies API provides read-only access to the distribution relationship structures managed by the AgentSync platform. It exposes the upline/downline hierarchies that define how carriers, agencies, IMOs, and producers are connected — the structural data that drives commission calculations, reporting, and compliance.

Hierarchies and Contracting: The Hierarchies API is built on top of the Contracting API data model. Hierarchy positions are derived from contract assignments and the upline relationships between them. You need existing carrier, product, and contract assignment data in AgentSync before hierarchy data is meaningful.

What is the Hierarchies API?

Insurance distribution runs on hierarchical contractual relationships. A producer contracts with an agency, the agency sits below an IMO, and the IMO connects to the carrier. Every commission payout, every "ready to sell" check, and every compliance review depends on accurately knowing this chain.

The Hierarchies API makes that chain queryable. It surfaces:

• Product hierarchies — which organizations hold contracted positions for a specific product
• Hierarchy nodes — the individual producer and organization positions in a hierarchy, including their upline relationship, commission level, states, assignment status, and contract details
• Point-in-time views — the hierarchy as it existed on any given date, not just today
• Changelog — an audit trail of every change made to a product hierarchy position

This is a read-only API. Hierarchy data is managed through the Contracting API (contract assignments and their upline relationships). The Hierarchies API gives you a structured, traversable view of the result.

Core Concepts

Product Hierarchy

A ProductHierarchy record represents an organization's contracted position for a specific product. It captures:

• Which organization holds this position (organizationId, organizationName)
• Which product it covers (productId, productName, lineOfBusinessName)
• When it was last modified (lastEditedAt, lastEditedByName)

Use the list and search endpoints to find the ProductHierarchy records relevant to your integration. The id from these records is used to fetch the hierarchy tree and changelog.

Hierarchy Node

A HierarchyNode represents a single position in the distribution hierarchy — a producer or organization at a particular level, for a specific product. The hierarchy tree endpoints return a flat list of nodes; each node includes a uplineContractAssignmentChangeId that points to its immediate upline node (or null for root nodes). A path array lists the full chain of contractAssignmentChangeId values from the root down to that node, making depth and ancestry immediately readable without recursive traversal.

Each node carries the full details of that position:

• contractAssignmentId — the underlying contract assignment
• contractAssignmentChangeId — the unique identifier for this node in the hierarchy
• uplineContractAssignmentChangeId — the parent node's ID (null if this is a root)
• path — ordered list of contractAssignmentChangeId values from root to this node
• producerName — the producer or organization at this position
• commissionLevelName, level — commission level name and numeric value
• assignmentStatusId, assignmentStatusName — current assignment status
• stateAbbreviations — states this position is contracted for
• startDate, endDate — active date range of this position
• active — whether this position (and its downlines) is currently active
• writingNumber — carrier-assigned writing number, if applicable
• uplineName, uplineAssignmentStatusName — display fields for the direct upline

Point-in-Time Snapshots

All hierarchy node endpoints accept a ?date parameter (yyyy-MM-dd). When provided, the API returns the hierarchy as it existed on that date. When omitted, it defaults to today.

This is essential for commissions use cases: "who was this producer's upline on the date of this transaction?"

Changelog

The changelog for a ProductHierarchy record captures every change to the position over time — who changed it, when, what the state was after the change. Each changelog entry records the full snapshot of the position at the time of the change, including producerName, uplineName, commissionLevelName, assignmentStatusName, and effective dates.

Key Features

Read Hierarchy Positions

Query which organizations hold product hierarchy positions for your account, filtered by product name or line of business.

Traverse the Hierarchy Tree

Get the flat list of all nodes for an organization, a specific product hierarchy, or an individual producer. Build the tree by grouping on uplineContractAssignmentChangeId, or use the path array to determine depth and ancestry without recursive traversal.

Point-in-Time History

Query the hierarchy as it existed on any historical date. Build audit trails that answer "who was above this producer on this date?" — critical for commission dispute resolution.

Audit Trail

The changelog endpoint tracks every change to a product hierarchy position: who made it, when, and what the full state was at that moment. Default sort is most-recent-first.

Hierarchy Tree Structure

The tree endpoints return a flat list of HierarchyNode objects. To reconstruct the tree:

1. Identify root nodes: uplineContractAssignmentChangeId == null
2. Group remaining nodes by uplineContractAssignmentChangeId
3. Recursively attach children to their parent using contractAssignmentChangeId as the key

Alternatively, use the path array directly:

• path.length == 1 → root node
• path.length == 2 → one level below root
• path[path.length - 2] → the immediate upline's contractAssignmentChangeId

Entity Relationships

ProductHierarchy (organizationId, productId)
  |-- organizationName, productName, lineOfBusinessName
  |-- lastEditedAt, lastEditedByName
  |
  |-- HierarchyNode (flat list, via /hierarchies endpoints)
  |     |-- contractAssignmentChangeId  (this node's ID)
  |     |-- uplineContractAssignmentChangeId  (parent node; null = root)
  |     |-- path[]  (full chain from root to this node)
  |     |-- producerName, commissionLevelName, assignmentStatusName
  |     |-- stateAbbreviations[], startDate, endDate, active
  |     |-- writingNumber, partnershipName
  |     |-- uplineName, uplineAssignmentStatusName
  |
  |-- HierarchyChangelogEntry (per-change snapshot, via /changelog endpoint)
        |-- contractAssignmentChangeId, contractAssignmentDisplayNumber
        |-- producerName, uplineName, commissionLevelName, writingNumber
        |-- contractAssignmentChangeAssignmentStatusName
        |-- modifiedDate, modifiedByName
        |-- effectiveDate, expirationDate, startDate, endDate

API Endpoints

All Hierarchies API endpoints share the same base URL as the Contracting API:

• Sandbox: https://api.sandbox.agentsync.io/contracting
• Production: https://api.agentsync.io/contracting

Use Cases

Lifecycle Event Detection

The Hierarchies API does not push events — use changelog polling to detect changes. See Detecting Hierarchy Changes for the polling pattern.

Read / Sync Patterns

• Pull the full flat node list for an organization at a point in time — use GET /organizations/{orgId}/hierarchies?date= for reconciliation
• Look up where a specific producer sits and who their upline is — use GET /organizations/{orgId}/persons/{personId}/hierarchies; uplineName and the path[] array give the full chain
• Retrieve all changes (CACs) grouped under a single contract assignment — filter the flat node list by contractAssignmentId
• Given a node, find its parent contract assignment — contractAssignmentId is on every HierarchyNode

Commission

• Read the commission level on any node — commissionLevelName and level on HierarchyNode
• Detect when a commission level changes — compare commissionLevelName across changelog entries for the same producer
• Read the annualization setting — annualizationName and annualizationProportion on HierarchyNode
• Detect when annualization changes — annualizationName in changelog entries

Org / Reporting

• Understand the full reporting chain above a producer (all uplines to the top) scoped by product — the path[] array on each node lists contractAssignmentChangeId values from root to the node; cross-reference the flat list to resolve names

Date-Based Queries

• Query the hierarchy as of any historical date — add ?date=yyyy-MM-dd to any tree endpoint
• Compare snapshots across dates to identify what changed between two points in time

Partnerships

• Identify which nodes belong to a partnership — partnershipId and partnershipName on HierarchyNode
• Detect whether an assignment uses a partnership arrangement or an individual one — check partnershipId != null

Audit and Compliance

• Use the changelog to verify when a hierarchy position changed and who made the change (modifiedByName, modifiedDate)
• Pull point-in-time snapshots to reconstruct the hierarchy on any past date
• Correlate contractAssignmentChangeId in changelog entries back to the full Contracting API record for complete audit trails

Detecting Hierarchy Changes

There are currently no webhook events specific to hierarchy changes. To detect updates in your integration, poll the changelog endpoint for each product hierarchy you monitor and compare modifiedDate against your last-synced timestamp. When changes are detected, pull the current node list to refresh your downstream data.

See Webhook Events for the current list of events — hierarchy lifecycle webhooks are planned for a future release.

Getting Started

Start here: The Hierarchies API Quick Start Guide walks through authentication, finding your organization, listing product hierarchies, and reading the hierarchy node list — with curl examples throughout.

For the full endpoint reference, see the interactive API Reference.

Support

Need help? Contact us at support@agentsync.io