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 are contracted to sell a specific product, and who their uplines are
• Hierarchy trees — the full upline/downline graph for an organization, a specific product, or a specific producer
• 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)
• Which carrier the product belongs to (carrierOrganizationId, carrierOrganizationName)
• Who the upline is (parentProductHierarchyId — links to another ProductHierarchy record)

The parentProductHierarchyId is how upline relationships are expressed. If Organization A is below Organization B for Product X, then A's ProductHierarchy record has parentProductHierarchyId pointing to B's ProductHierarchy record for the same product.

Hierarchy Tree

The hierarchy tree endpoints return a recursive structure of HierarchyNode objects. Each node represents an organization or producer at a position in the tree and contains a children array for everything one level below. You can traverse the full downline by walking the tree.

Each node carries:

• id — the node ID
• name — display name
• organizationId — the organization this node belongs to
• personId / firmId — the individual or firm producer (when the node represents a producer position)
• npn — the producer's National Producer Number
• contractAssignmentId — the underlying contract assignment
• children[] — the downlines directly below this node

Point-in-Time Snapshots

All hierarchy tree 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

Every ProductHierarchy record maintains a changelog of changes (changeType, description, modifiedDate, modifiedBy). Use this for audit trails and reconciliation with commission systems.

Key Features

Read Hierarchy Positions

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

Traverse Upline/Downline Trees

Get the full recursive tree for an organization, a specific product hierarchy, or an individual producer. Traverse uplines and downlines without assembling them from raw contract data.

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 record: who made it, when, and what changed. Default sort is most-recent-first.

Entity Relationships

ProductHierarchy (organizationId, productId, carrierOrganizationId)
  |-- organizationName, productName, lineOfBusinessName, carrierOrganizationName
  |-- parentProductHierarchyId → (upline ProductHierarchy)
  |-- createdDate, modifiedDate, createdBy, modifiedBy
  |
  |-- HierarchyNode (tree view, via /hierarchies endpoints)
  |     |-- id, name, organizationId, npn
  |     |-- personId, firmId (producer-level nodes)
  |     |-- contractAssignmentId (the underlying contract assignment)
  |     |-- children[] (recursive downlines)
  |
  |-- HierarchyChangelogEntry (audit trail, via /changelog endpoint)
        |-- changeType, description
        |-- modifiedDate, modifiedBy

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

Commissions System Integration

• Fetch the hierarchy tree for a product to determine the full upline chain at the time of a transaction
• Use ?date to retrieve historical hierarchy snapshots for commission reconciliation
• Detect hierarchy changes using the changelog, then trigger commission system updates

Distribution Visibility

• Build a read-only view of your full distribution network — who sits where, for which products
• Query a specific producer's position and uplines across products in a single call
• Search product hierarchies by carrier or line of business to scope views to relevant segments

Audit and Compliance

• Use the changelog to verify when a hierarchy position changed and who made the change
• Pull point-in-time snapshots to reconstruct the state of the hierarchy on any past date
• Correlate hierarchy changes with contract assignment changes for complete audit trails

Ready-to-Sell Validation

• Verify that a producer has an upline in place for a product before allowing transactions
• Detect hierarchy gaps (missing uplines) before they delay onboarding or cause payout errors

Getting Started

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

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

Support

Need help? Contact us at support@agentsync.io