Contracting & Hierarchies API
List the commission levels available to the calling customer
Returns the commission levels the calling customer can use across all of their products as a
token-paginated collection, so the customer’s commission configuration can be read in one
call. This covers both distribution and carrier callers: a commission level is included when
it is assigned to the caller’s organization, and when the caller’s organization owns the
product the commission level belongs to. A commission level that is both owned and assigned
is returned once. Each row carries its product and carrier context; on an owned commission
level carrierOrganizationId is the caller’s own organization and active is always true,
because ownership has no assignment record to deactivate. Results are scoped to the caller;
another customer’s commission levels are never returned.
Note: updated_since is based on the row’s modified_date (commission-level/product updates) and
does not reflect assignment-only changes if those records did not change.
get
Query Parameters
page_tokenstring
Opaque continuation token from a previous response’s page.nextToken. Omit for the first
page.
page_sizeinteger
Maximum number of items to return. Defaults to 25; values outside [1, 250] are rejected
with 400 (not clamped).
Default:25
>= 1<= 250
updated_sincestring(date-time)
Return only contracts modified at or after this RFC3339 UTC timestamp (inclusive). Modified
time tracks any column change, so “modified” does not necessarily mean a
business-meaningful change. Best used as a high-water mark for incremental sync: a pagination
run is not a point-in-time snapshot, so records updated mid-run may first appear on a later poll.
Example:2026-06-01T00:00:00Z
Response
application/json
Response
application/json
A page of assigned commission levels.
AssignedCommissionLevelV2Page
A token-paginated page of the commission levels available to the caller (plain envelope, no HAL wrappers).
itemsarray[object]required
A commission level the calling customer can use - assigned to their organization, or owned by it as the carrier - with its product and carrier context.
Show Child Parameters
pageobjectrequired
Pagination metadata for a V2 list response.
Show Child Parameters
application/json
Hierarchies
Read-only views of an organization’s contract-assignment hierarchy and the candidates eligible to be selected as upline placements.
List the hierarchy nodes for an organization
Returns the organization’s contract-assignment hierarchy as a token-paginated flat list of
nodes. The node key is contractAssignmentId — the stable identity of a producer’s
placement for a product — and tree linkage is uplineContractAssignmentId (null on root
nodes). Node keys correlate with the hierarchy.producer.* webhook events, which link
nodes the same way. Pass as_of to view the hierarchy as it existed on a historical date;
omit it for the current state. Results are scoped to the caller’s organization(s).
get
Query Parameters
as_ofstring(date)
Return the hierarchy as it existed on this date (yyyy-MM-dd). Omit for the current
state.
Example:2026-06-22
page_tokenstring
Opaque continuation token from a previous response’s page.nextToken. Omit for the first
page.
page_sizeinteger
Maximum number of items to return. Defaults to 25; values outside [1, 250] are rejected
with 400 (not clamped).
Default:25
>= 1<= 250
Path Parameters
organizationIdstring(uuid)required
The organization whose hierarchy to list.
Response
application/json
Response
application/json
A page of hierarchy nodes.
HierarchyNodeV2Page
A token-paginated page of hierarchy nodes (plain envelope, no HAL wrappers).
itemsarray[object]required
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.
Show Child Parameters
pageobjectrequired
Pagination metadata for a V2 list response.
Show Child Parameters
application/json
List the candidates eligible to be selected as an upline for a contract-assignment-change
Returns the contract-assignment changes eligible to be selected as the upline for the given
contract-assignment-change, as a token-paginated collection. Candidates share the change’s
product and overlap its commission-terms window. Results are scoped to the caller’s
organization(s).
get
Query Parameters
page_tokenstring
Opaque continuation token from a previous response’s page.nextToken. Omit for the first
page.
page_sizeinteger
Maximum number of items to return. Defaults to 25; values outside [1, 250] are rejected
with 400 (not clamped).
Default:25
>= 1<= 250
Path Parameters
idstring(uuid)required
The contract-assignment-change to find available uplines for.
Response
application/json
Response
application/json
A page of available upline candidates.
AvailableUplineChangeV2Page
A token-paginated page of available upline candidates (plain envelope, no HAL wrappers).
itemsarray[object]required
A contract-assignment change eligible to be selected as an upline, scoped to a
contract-assignment or contract-assignment-change.
Show Child Parameters
pageobjectrequired
Pagination metadata for a V2 list response.
Show Child Parameters
application/json
List the candidates eligible to be selected as an upline for a contract-assignment
Returns the contract-assignment changes eligible to be selected as an upline for a new change
on the given contract-assignment over the supplied date range, as a token-paginated
collection. Candidates share the assignment’s product and overlap the start_date/end_date
window. Results are scoped to the caller’s organization(s).
get
Query Parameters
start_datestring(date)required
Start of the prospective change’s commission-terms window. Candidates whose window is
still open on or after this date are included.
Example:2026-01-01
end_datestring(date)
End of the prospective change’s commission-terms window. When provided, candidates whose
window starts after this date are excluded.
Example:2026-12-31
page_tokenstring
Opaque continuation token from a previous response’s page.nextToken. Omit for the first
page.
page_sizeinteger
Maximum number of items to return. Defaults to 25; values outside [1, 250] are rejected
with 400 (not clamped).
Default:25
>= 1<= 250
Path Parameters
idstring(uuid)required
The contract-assignment to find available uplines for.
Response
application/json
Response
application/json
A page of available upline candidates.
AvailableUplineChangeV2Page
A token-paginated page of available upline candidates (plain envelope, no HAL wrappers).
itemsarray[object]required
A contract-assignment change eligible to be selected as an upline, scoped to a
contract-assignment or contract-assignment-change.
Show Child Parameters
pageobjectrequired
Pagination metadata for a V2 list response.
Show Child Parameters
application/json