Agents API¶
Comprehensive agent search, network management, and detailed information retrieval.
Overview¶
Agents API Features
- Agent Search: Find agents with advanced filtering including email and phone
- Agent Details: Get individual agent information and cap details
- Network Management: Access sponsor trees and downlines
- Contact Information: Get agent details by email, ID, or phone
- Geographic Filtering: Search by location and region
Quick Start¶
from rezen import RezenClient
client = RezenClient()
# Get a single agent by ID
agent = client.agents.get_agent("agent-uuid")
print(f"Agent: {agent['name']}")
# Simple agent search by name
agents = client.agents.search_active_agents(name="John", page_size=10)
print(f"Found {len(agents)} agents named John")
from rezen import RezenClient
client = RezenClient()
# Search by email
agents = client.agents.search_active_agents(email="john@example.com")
# Search by phone
agents = client.agents.search_active_agents(phone="+1234567890")
# Using backward compatibility method
agents = client.agents.agent_search(email="john@example.com")
agents = client.agents.agent_search(phone="+1234567890")
from rezen import RezenClient
from rezen.enums import Country, StateOrProvince, AgentSortField
client = RezenClient()
# Geographic search with sorting
agents = client.agents.search_active_agents(
country=[Country.UNITED_STATES],
state_or_province=[StateOrProvince.CALIFORNIA],
sort_by=[AgentSortField.LAST_NAME],
page_size=50
)
from rezen import RezenClient
from rezen.exceptions import RezenError, NotFoundError
client = RezenClient()
try:
agent = client.agents.get_agent("agent-uuid")
print(f"Found agent: {agent['name']}")
except NotFoundError:
print("Agent not found")
except RezenError as e:
print(f"API error occurred: {e}")
Core Methods¶
Get Single Agent¶
Get a single agent by ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id | str | The agent's ID | required |
Returns:
| Type | Description |
|---|---|
Dict[str, Any] | Dict containing agent information |
Raises:
| Type | Description |
|---|---|
RezenError | If agent not found or API error |
Get Agent Cap Information¶
Get agent's cap information.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id | str | UUID of the agent | required |
Returns:
| Type | Description |
|---|---|
Dict[str, Any] | Agent's cap information |
Raises:
| Type | Description |
|---|---|
RezenError | If the API request fails |
Search Active Agents¶
Search for active agents.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
page_number | Optional[int] | Page number for pagination (default: 0) | None |
page_size | Optional[int] | Page size for pagination (default: 20) | None |
sort_direction | Optional[Union[SortDirection, str]] | Sort direction (default: ASC) | None |
sort_by | Optional[List[Union[AgentSortField, str]]] | Fields to sort by (default: ["FIRST_NAME", "LAST_NAME"]) | None |
name | Optional[str] | Filter by agent name | None |
email | Optional[str] | Filter by email address | None |
phone | Optional[str] | Filter by phone number | None |
non_reportable | Optional[List[bool]] | Filter by non-reportable status | None |
country | Optional[List[Union[Country, str]]] | Filter by country | None |
state_or_province | Optional[List[Union[StateOrProvince, str]]] | Filter by state or province | None |
Returns:
| Type | Description |
|---|---|
Dict[str, Any] | Search results for active agents |
Raises:
| Type | Description |
|---|---|
RezenError | If the API request fails |
New Parameters
The search_active_agents method now supports email and phone parameters for direct contact search.
Agent Search (Backward Compatibility)¶
Search agents by email or phone - backward compatibility method.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
email | str | Email address to search for | '' |
phone | str | Phone number to search for | '' |
Returns:
| Type | Description |
|---|---|
Dict[str, Any] | Dict containing search results |
Raises:
| Type | Description |
|---|---|
RezenError | If the API request fails |
Get Agent by Email¶
Get agent(s) by email address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
email_address | str | Email address to search for | required |
Returns:
| Type | Description |
|---|---|
Dict[str, Any] | Agent information matching the email address |
Raises:
| Type | Description |
|---|---|
RezenError | If the API request fails |
Get Agents by IDs¶
Get agents by ids (limit 20).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_ids | List[str] | List of agent UUIDs (maximum 20) | required |
Returns:
| Type | Description |
|---|---|
Dict[str, Any] | Agents information for the specified IDs |
Raises:
| Type | Description |
|---|---|
RezenError | If the API request fails |
ValidationError | If more than 20 agent IDs are provided |
Network Hierarchy¶
Get agent's sponsor tree.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id | str | UUID of the agent | required |
Returns:
| Type | Description |
|---|---|
Dict[str, Any] | Agent's sponsor tree information |
Raises:
| Type | Description |
|---|---|
RezenError | If the API request fails |
Get agents in the network within a specific tier of the given agent.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent_id | str | UUID of the agent | required |
tier | int | Tier level to retrieve | required |
updated_at_from | Optional[date] | Start date for updatedAt filter (e.g., "2025-01-01") | None |
updated_at_to | Optional[date] | End date for updatedAt filter (e.g., "2025-01-31") | None |
status_in | Optional[List[Union[AgentStatus, str]]] | Filter agents by status, defaults to ACTIVE if not specified | None |
page_number | Optional[int] | Page number for pagination (default: 0) | None |
page_size | Optional[int] | Page size for pagination (default: 20) | None |
Returns:
| Type | Description |
|---|---|
Dict[str, Any] | Downline agents information for the specified tier |
Raises:
| Type | Description |
|---|---|
RezenError | If the API request fails |
Search Examples¶
Advanced Agent Search
Agent Information¶
Agent Details
Get comprehensive agent information including cap details and profile scores.
Agent Information Retrieval
# Get single agent details
agent = client.agents.get_agent("agent-uuid")
# Get agent cap information
cap_info = client.agents.get_cap_info("agent-uuid")
# Get profile score
profile_score = client.agents.get_profile_score("agent-uuid")
# Get payment details
payment_details = client.agents.get_payment_details("agent-uuid")
Network Management¶
Agent Hierarchy
The ReZEN platform supports agent network hierarchies with sponsor trees and downlines.
Network Analysis
# Get agent's sponsor tree
sponsor_tree = client.agents.get_sponsor_tree("agent-uuid")
# Get first-tier downline
downline = client.agents.get_down_line_agents(
agent_id="agent-uuid",
tier=1,
status_in=["ACTIVE"]
)
# Get front line agents info
front_line = client.agents.get_front_line_agents_info("agent-uuid")
Next Steps¶
-
:material-account-group: Teams API
Manage team information and memberships
-
:material-hammer-wrench: Transaction Builder
Add agents to transactions
-
:material-book-open: Directory API
Access additional agent directory services