Teams and hierarchy

Agents are arranged in a hierarchy: each agent has a direct upline (the agent they report to) and an agent level (a numeric rank used for things like commission splits). Hierarchies are kept per team. The only supported team today is default.

Both the direct upline and the level are effective-dated, so AgencyMax knows who reported to whom, and at what level, on any date.

Operations

All of these operations are under /teams/{team}.

Operation	Scope	Description
PATCH /teams/{team}/members/{agentCode}	write:agents	Change an agent's current direct upline and/or level, effective today.
GET /teams/{team}/assigned-uplines	read:agents	Direct upline assignment history.
POST /teams/{team}/assigned-uplines	write:agents	Apply a direct upline period to the history.
GET /teams/{team}/assigned-levels	read:agents	Agent level assignment history.
POST /teams/{team}/assigned-levels	write:agents	Apply a level period to the history.
GET /teams/{team}/upline-members	read:agents	Flattened upline relationships: every agent above each agent.
GET /teams/{team}/downline-members	read:agents	Flattened downline relationships: every agent below each agent.
GET/POST /teams/{team}/agent-levels, GET/PATCH/DELETE /teams/{team}/agent-levels/{value}	read:agents / write:agents	The agent level definitions. See Reference data.

Changing the current upline or level

PATCH /agency-management/acme/teams/default/members/A1051
Content-Type: application/json

{
  "membership": { "directUpline": "A1001", "level": 20 },
  "initiator": "jsmith@acme-agency.com"
}

Either property can be left out to keep it unchanged.

Changing history

To record a change that took effect on another date, or for a fixed period, post a history period:

POST /agency-management/acme/teams/default/assigned-uplines

{
  "agentCode": "A1051",
  "uplineAgentCode": "A1001",
  "effectiveFrom": "2026-07-01",
  "initiator": "jsmith@acme-agency.com"
}

POST /agency-management/acme/teams/default/assigned-levels

{
  "agentCode": "A1051",
  "level": 20,
  "effectiveFrom": "2026-07-01",
  "effectiveThrough": "2026-12-31",
  "initiator": "jsmith@acme-agency.com"
}

Periods are merged into the existing history with the effective-dated history rules: the new period wins and its neighbours are adjusted.

Validation rules

• The upline must be an existing agent.
• Circular hierarchies are rejected. An agent can't be made the upline of one of its own uplines, directly or indirectly.
• The level must be one of the team's configured agent levels.

Reading the hierarchy

downline-members and upline-members return the hierarchy flattened: one row for each ancestor/descendant pair, not just direct relationships. That makes questions such as "everyone in A1001's organization" easy to answer.

GET /teams/default/downline-members filters:

Parameter	Description
agentCode	The agent whose downline you want.
downlineAgentCode	Limit to a specific downline agent.
downlineLevel	An exact downline agent level. When set, minDownlineLevel and maxDownlineLevel are ignored.
minDownlineLevel, maxDownlineLevel	A range of downline agent levels.

The flattened hierarchy is rebuilt in the background after hierarchy changes. When a rebuild finishes, the HierarchyBuildCompleted event is published. Wait for that event before you re-read downline-members or upline-members after a bulk change.