Hierarchies API: Quick Start Guide

This guide walks through querying AgentSync's distribution hierarchy data — finding the product hierarchies for your organization, traversing the upline/downline tree, and using point-in-time snapshots for commissions reconciliation.

Who this is for: Engineers at commissions platforms, carriers, or agencies integrating with AgentSync hierarchy data.

What you'll do: Authenticate, find your organization, list product hierarchies, retrieve the hierarchy tree, and pull a historical snapshot.

Before You Start

Sandbox credentials with the rino_api_agency_read scope — email support@agentsync.io to request access
Access token — follow the Authentication guide before proceeding
Your AgentSync organization ID (UUID) — see Step 1 below; you can also obtain this from your AgentSync account team
Hierarchies API endpoints use the same /contracting base URL as the Contracting API — see API Base URLs

Prerequisite data: Hierarchy data is built from contract assignments in the Contracting API. If your account has no carriers, products, or contract assignments yet, see the Contracting API Quick Start Guide first.

Step 1: Get Your Organization ID

The Hierarchies API uses organization IDs to scope queries. Your organization ID is a UUID that identifies your agency or carrier in AgentSync. If you already know it, skip to Step 2.

Fetch it from the Contracting API using your carrier or agency name:

curl -X GET \
  "https://api.sandbox.agentsync.io/contracting/v1/customers/carriers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response:

{
  "_embedded": {
    "carriers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Acme Insurance Company",
        "naic": "12345"
      }
    ]
  }
}

The id field in the carrier response is the organization ID you'll use in Hierarchies API calls.

Step 2: List Product Hierarchies for Your Organization

With your organization ID, fetch all product hierarchy records. Each record represents a position in the distribution chain for a specific product.

curl -X GET \
  "https://api.sandbox.agentsync.io/contracting/v1/organizations/ORG_ID/productHierarchies" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace ORG_ID with your organization UUID from Step 1.

Example response:

{
  "_embedded": {
    "decoratedProductHierarchyList": [
      {
        "id": "ph-uuid-1111",
        "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "organizationName": "Acme IMO",
        "productId": "prod-uuid-2222",
        "productName": "Term Life 10-Year",
        "lineOfBusinessName": "Life",
        "carrierOrganizationId": "carrier-uuid-3333",
        "carrierOrganizationName": "Acme Insurance Company",
        "parentProductHierarchyId": null,
        "createdDate": "2024-01-15T10:30:00Z",
        "modifiedDate": "2025-03-01T08:00:00Z"
      },
      {
        "id": "ph-uuid-2222",
        "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "organizationName": "Acme IMO",
        "productId": "prod-uuid-3333",
        "productName": "Whole Life",
        "lineOfBusinessName": "Life",
        "carrierOrganizationId": "carrier-uuid-3333",
        "carrierOrganizationName": "Acme Insurance Company",
        "parentProductHierarchyId": "ph-uuid-0000",
        "createdDate": "2024-02-01T09:00:00Z",
        "modifiedDate": "2025-03-01T08:00:00Z"
      }
    ]
  },
  "_links": {
    "self": { "href": "/contracting/v1/organizations/a1b2c3d4.../productHierarchies" }
  },
  "page": {
    "size": 250,
    "totalElements": 2,
    "totalPages": 1,
    "number": 0
  }
}

Key fields:

id — the product hierarchy record ID, used in subsequent calls
parentProductHierarchyId — the upline position; null means this organization is at the top of the hierarchy for this product
organizationName, productName, carrierOrganizationName — display labels for the position

Pagination: Default page size is 250, maximum 1000. Pass ?size=1000&page=0 to control paging.

Searching Product Hierarchies

To filter by carrier or line of business, use the /search endpoint instead:

curl -X GET \
  "https://api.sandbox.agentsync.io/contracting/v1/organizations/ORG_ID/productHierarchies/search?carrierOrganizationId=CARRIER_ORG_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Available search parameters:

Parameter	Type	Description
`productName`	string	Partial match on product name
`carrierOrganizationId`	UUID	Filter to a specific carrier
`lineOfBusinessIds`	UUID (repeatable)	Filter to specific lines of business

Step 3: Get the Hierarchy Tree

The tree endpoints return the full upline/downline structure as a recursive HierarchyNode array. Each node's children array contains the organizations or producers one level below.

Fetch the hierarchy tree for a specific product hierarchy record:

curl -X GET \
  "https://api.sandbox.agentsync.io/contracting/v1/productHierarchies/PH_ID/hierarchies" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace PH_ID with a product hierarchy ID from Step 2.

Example response:

[
  {
    "id": "node-uuid-1",
    "name": "Acme IMO",
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "personId": null,
    "firmId": null,
    "npn": null,
    "contractAssignmentId": null,
    "children": [
      {
        "id": "node-uuid-2",
        "name": "Westside Agency",
        "organizationId": "org-uuid-aaaa",
        "personId": null,
        "firmId": null,
        "npn": null,
        "contractAssignmentId": null,
        "children": [
          {
            "id": "node-uuid-3",
            "name": "Joe Producer",
            "organizationId": "org-uuid-bbbb",
            "personId": "person-uuid-cccc",
            "firmId": null,
            "npn": "15645555",
            "contractAssignmentId": "ca-uuid-dddd",
            "children": []
          }
        ]
      }
    ]
  }
]

The tree is returned as an array of root nodes. Walk the children arrays to traverse downlines. Nodes with a personId or firmId are producer-level positions; nodes without are organizational positions.

Tree by Organization

To get the full hierarchy tree for an entire organization (all products):

curl -X GET \
  "https://api.sandbox.agentsync.io/contracting/v1/organizations/ORG_ID/hierarchies" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Tree for a Specific Producer

To get the hierarchy view scoped to a specific person within an organization:

curl -X GET \
  "https://api.sandbox.agentsync.io/contracting/v1/organizations/ORG_ID/persons/PERSON_ID/hierarchies" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace PERSON_ID with the producer's AgentSync person UUID (from the Producer Profile API or Contracting API contract assignment data).

Step 4: Get a Point-in-Time Snapshot

All hierarchy tree endpoints accept an optional ?date parameter (yyyy-MM-dd). When provided, the response reflects the hierarchy as it existed on that date.

curl -X GET \
  "https://api.sandbox.agentsync.io/contracting/v1/productHierarchies/PH_ID/hierarchies?date=2025-01-15" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This is the primary mechanism for commissions reconciliation — query the hierarchy as of the transaction date to confirm who the upline was at that moment.

No date provided → today's hierarchy. Always supply an explicit ?date when querying for historical purposes. Omitting it returns the current state, which may have changed since the transaction.

Step 5: Read the Changelog

The changelog records every change made to a product hierarchy record, sorted most-recent-first by default.

curl -X GET \
  "https://api.sandbox.agentsync.io/contracting/v1/productHierarchies/PH_ID/changelog" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response:

{
  "_embedded": {
    "hierarchyChangelogViewList": [
      {
        "id": "cl-uuid-1111",
        "productHierarchyId": "ph-uuid-1111",
        "changeType": "UPLINE_CHANGED",
        "description": "Upline updated to Westside Agency",
        "modifiedDate": "2025-03-01T08:00:00Z",
        "modifiedBy": "admin@acme.com"
      },
      {
        "id": "cl-uuid-0000",
        "productHierarchyId": "ph-uuid-1111",
        "changeType": "CREATED",
        "description": null,
        "modifiedDate": "2024-01-15T10:30:00Z",
        "modifiedBy": "admin@acme.com"
      }
    ]
  },
  "_links": {
    "self": { "href": "/contracting/v1/productHierarchies/ph-uuid-1111/changelog" }
  },
  "page": {
    "size": 250,
    "totalElements": 2,
    "totalPages": 1,
    "number": 0
  }
}

Use the modifiedDate from changelog entries alongside ?date queries on the hierarchy tree to reconstruct exactly what happened and when.

Recommended Workflows

Commissions Integration

1. GET /organizations/{orgId}/productHierarchies/search?carrierOrganizationId={carrierId}
   → Find all product hierarchy records for a carrier

2. GET /productHierarchies/{phId}/hierarchies?date={transactionDate}
   → Get the hierarchy as of the transaction date

3. Walk children[] to build the full upline chain for the transaction

4. GET /productHierarchies/{phId}/changelog
   → Detect changes; trigger recalculation when changeType signals a hierarchy shift

Daily Sync

There are currently no webhook events specific to hierarchy changes. To detect hierarchy updates in your integration:

Poll the changelog endpoint for each product hierarchy you monitor
Compare modifiedDate against your last-synced timestamp
When changes are detected, pull the current tree to refresh your downstream data

See Webhook Events for the full list of events — hierarchy change webhooks may be added in a future release.

Endpoint Reference Summary

All endpoints use base URL https://api.sandbox.agentsync.io/contracting (sandbox) or https://api.agentsync.io/contracting (production).

Endpoint	Default Page Size	Sort Default	Key Query Params
`GET /v1/productHierarchies/{id}`	—	—	—
`GET /v1/organizations/{orgId}/productHierarchies`	250	`productName`	`page`, `size`, `sort`
`GET /v1/organizations/{orgId}/productHierarchies/search`	250	`productName`	`productName`, `carrierOrganizationId`, `lineOfBusinessIds`
`GET /v1/productHierarchies/{id}/hierarchies`	—	—	`date` (yyyy-MM-dd)
`GET /v1/organizations/{orgId}/hierarchies`	—	—	`date` (yyyy-MM-dd)
`GET /v1/organizations/{orgId}/persons/{personId}/hierarchies`	—	—	`date` (yyyy-MM-dd)
`GET /v1/productHierarchies/{id}/changelog`	250	`modifiedDate,desc`	`page`, `size`, `sort`

Error Handling

Hierarchies API errors follow the same format as the Contracting API:

{
  "status": 404,
  "timestamp": 1773867190,
  "messages": ["Product hierarchy not found."],
  "path": "/contracting/v1/productHierarchies/unknown-id",
  "error": "Not Found"
}

See API Status Codes for the full list of expected codes.

Support

Need help? Contact us at support@agentsync.io