Directory API¶

Access directory services for agent and contact information with dedicated client functionality.

Overview¶

Directory API Features

Dedicated Client: Separate client for directory services
Contact Search: Find contacts and agent information
Different Endpoint: Uses specialized directory API endpoint
Enhanced Search: Advanced contact discovery capabilities

Client Setup¶

Separate Directory Client

The Directory API uses a dedicated client with its own endpoint configuration.

from rezen import DirectoryClient

# Initialize directory client
directory = DirectoryClient()

# Or with explicit configuration
directory = DirectoryClient(
    api_key="your_api_key_here",
    base_url="https://yenta.therealbrokerage.com/api/v1"
)

Core Methods¶

Directory Client Operations¶

Bases: BaseClient

Client for ReZEN Directory API endpoints.

Provides access to directory functionality including: - Vendor management (create, update, search, archive) - Person management (create, update, search, link/unlink) - Directory entry search across vendors and persons - Role management and W9 file handling

Initialize the Directory API client.

Parameters:

Name	Type	Description	Default
`api_key`	`Optional[str]`	ReZEN API key for authentication	`None`
`base_url`	`Optional[str]`	Base URL for the directory API. Defaults to yenta production URL	`None`

`archive_person(person_id, archive=True)` ¶

Archive or unarchive a person.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	UUID of the person	required
`archive`	`bool`	True to archive, False to unarchive	`True`

Returns:

Type	Description
`Dict[str, Any]`	Updated person data

Raises:

Type	Description
`RezenError`	If the API request fails

`archive_vendor(vendor_id, archive=True)` ¶

Archive or unarchive a vendor.

Parameters:

Name	Type	Description	Default
`vendor_id`	`str`	UUID of the vendor	required
`archive`	`bool`	True to archive, False to unarchive	`True`

Returns:

Type	Description
`Dict[str, Any]`	Updated vendor data

Raises:

Type	Description
`RezenError`	If the API request fails

`create_person(person_data, owner_agent_id=None, owner_team_id=None)` ¶

Create a person.

Parameters:

Name	Type	Description	Default
`person_data`	`Dict[str, Any]`	Person creation data	required
`owner_agent_id`	`Optional[str]`	Owner agent ID	`None`
`owner_team_id`	`Optional[str]`	Owner team ID	`None`

Returns:

Type	Description
`Dict[str, Any]`	Created person response data

Raises:

Type	Description
`RezenError`	If the API request fails

`create_vendor(vendor_data)` ¶

Create a vendor.

Parameters:

Name	Type	Description	Default
`vendor_data`	`Dict[str, Any]`	Vendor creation data	required

Returns:

Type	Description
`Dict[str, Any]`	Created vendor response data

Raises:

Type	Description
`RezenError`	If the API request fails

`get_permitted_roles(entry_type=None)` ¶

Get roles available for directory entries.

Parameters:

Name	Type	Description	Default
`entry_type`	`Optional[Union[DirectoryEntryType, str]]`	Filter by entry type (VENDOR or PERSON)	`None`

Returns:

Type	Description
`Dict[str, Any]`	Available roles for directory entries

Raises:

Type	Description
`RezenError`	If the API request fails

`get_person(person_id)` ¶

Get person by id.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	UUID of the person	required

Returns:

Type	Description
`Dict[str, Any]`	Person data

Raises:

Type	Description
`RezenError`	If the API request fails

`get_vendor(vendor_id)` ¶

Get vendor by id.

Parameters:

Name	Type	Description	Default
`vendor_id`	`str`	UUID of the vendor	required

Returns:

Type	Description
`Dict[str, Any]`	Vendor data

Raises:

Type	Description
`RezenError`	If the API request fails

`get_vendor_w9_url(vendor_id)` ¶

Get a vendor's W9 URL.

Parameters:

Name	Type	Description	Default
`vendor_id`	`str`	UUID of the vendor	required

Returns:

Type	Description
`str`	W9 file URL

Raises:

Type	Description
`RezenError`	If the API request fails

`link_person(person_id, link_data)` ¶

Link a person to a vendor.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	UUID of the person	required
`link_data`	`Dict[str, Any]`	Link data containing vendor information	required

Returns:

Type	Description
`Dict[str, Any]`	Updated person data

Raises:

Type	Description
`RezenError`	If the API request fails

`search_all_entries(page_number, page_size, is_archived=None, is_verified=None, search_text=None, national_business_id=None, name=None, email_address=None, phone_number=None, street=None, city=None, postal=None, state_or_province=None, country=None, administrative_area_ids=None, roles=None, created_by=None, entry_id=None, sort_by=None)` ¶

Get all vendors and persons with paging, sorting, and filtering.

Parameters:

Name	Type	Description	Default
`page_number`	`int`	Page number for pagination	required
`page_size`	`int`	Page size for pagination	required
`is_archived`	`Optional[bool]`	Filter by archived status	`None`
`is_verified`	`Optional[bool]`	Filter by verified status	`None`
`search_text`	`Optional[str]`	Search text	`None`
`national_business_id`	`Optional[str]`	Filter by national business ID	`None`
`name`	`Optional[str]`	Filter by name	`None`
`email_address`	`Optional[str]`	Filter by email address	`None`
`phone_number`	`Optional[str]`	Filter by phone number	`None`
`street`	`Optional[str]`	Filter by street address	`None`
`city`	`Optional[str]`	Filter by city	`None`
`postal`	`Optional[str]`	Filter by postal code	`None`
`state_or_province`	`Optional[Union[StateOrProvince, str]]`	Filter by state or province	`None`
`country`	`Optional[Union[Country, str]]`	Filter by country	`None`
`administrative_area_ids`	`Optional[List[str]]`	Filter by administrative area IDs	`None`
`roles`	`Optional[List[Union[DirectoryRole, str]]]`	Filter by roles	`None`
`created_by`	`Optional[str]`	Filter by creator UUID	`None`
`entry_id`	`Optional[str]`	Filter by entry ID	`None`
`sort_by`	`Optional[List[Union[DirectoryEntrySortField, str]]]`	Fields to sort by	`None`

Returns:

Type	Description
`Dict[str, Any]`	Paginated directory entry search results

Raises:

Type	Description
`RezenError`	If the API request fails

`search_persons(page_number, page_size, is_archived=None, is_public=None, is_linked_to_vendor=None, search_text=None, first_name=None, last_name=None, email_address=None, phone_number=None, roles=None, sort_by=None)` ¶

Get all persons with paging, sorting, and filtering.

Parameters:

Name	Type	Description	Default
`page_number`	`int`	Page number for pagination	required
`page_size`	`int`	Page size for pagination	required
`is_archived`	`Optional[bool]`	Filter by archived status	`None`
`is_public`	`Optional[bool]`	Filter by public status	`None`
`is_linked_to_vendor`	`Optional[bool]`	Filter by whether person is linked to vendor	`None`
`search_text`	`Optional[str]`	Search text	`None`
`first_name`	`Optional[str]`	Filter by first name	`None`
`last_name`	`Optional[str]`	Filter by last name	`None`
`email_address`	`Optional[str]`	Filter by email address	`None`
`phone_number`	`Optional[str]`	Filter by phone number	`None`
`roles`	`Optional[List[Union[DirectoryRole, str]]]`	Filter by roles	`None`
`sort_by`	`Optional[List[Union[PersonSortField, str]]]`	Fields to sort by	`None`

Returns:

Type	Description
`Dict[str, Any]`	Paginated person search results

Raises:

Type	Description
`RezenError`	If the API request fails

`search_vendors(page_number, page_size, is_archived=None, is_verified=None, has_linked_persons=None, search_text=None, national_business_id=None, name=None, email_address=None, phone_number=None, street=None, city=None, postal=None, state_or_province=None, country=None, administrative_area_ids=None, roles=None, sort_by=None)` ¶

Get all vendors with paging, sorting, and filtering.

Parameters:

Name	Type	Description	Default
`page_number`	`int`	Page number for pagination	required
`page_size`	`int`	Page size for pagination	required
`is_archived`	`Optional[bool]`	Filter by archived status	`None`
`is_verified`	`Optional[bool]`	Filter by verified status	`None`
`has_linked_persons`	`Optional[bool]`	Filter by whether vendor has linked persons	`None`
`search_text`	`Optional[str]`	Search text	`None`
`national_business_id`	`Optional[str]`	Filter by national business ID	`None`
`name`	`Optional[str]`	Filter by name	`None`
`email_address`	`Optional[str]`	Filter by email address	`None`
`phone_number`	`Optional[str]`	Filter by phone number	`None`
`street`	`Optional[str]`	Filter by street address	`None`
`city`	`Optional[str]`	Filter by city	`None`
`postal`	`Optional[str]`	Filter by postal code	`None`
`state_or_province`	`Optional[Union[StateOrProvince, str]]`	Filter by state or province	`None`
`country`	`Optional[Union[Country, str]]`	Filter by country	`None`
`administrative_area_ids`	`Optional[List[str]]`	Filter by administrative area IDs	`None`
`roles`	`Optional[List[Union[DirectoryRole, str]]]`	Filter by roles	`None`
`sort_by`	`Optional[List[Union[VendorSortField, str]]]`	Fields to sort by	`None`

Returns:

Type	Description
`Dict[str, Any]`	Paginated vendor search results

Raises:

Type	Description
`RezenError`	If the API request fails

`unlink_person(person_id)` ¶

Unlink a person from its linked vendor.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	UUID of the person	required

Returns:

Type	Description
`Dict[str, Any]`	Updated person data

Raises:

Type	Description
`RezenError`	If the API request fails

`update_person(person_id, person_data)` ¶

Update person by id.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	UUID of the person	required
`person_data`	`Dict[str, Any]`	Updated person data	required

Returns:

Type	Description
`Dict[str, Any]`	Updated person data

Raises:

Type	Description
`RezenError`	If the API request fails

`update_vendor(vendor_id, vendor_data)` ¶

Update vendor by id.

Parameters:

Name	Type	Description	Default
`vendor_id`	`str`	UUID of the vendor	required
`vendor_data`	`Dict[str, Any]`	Updated vendor data	required

Returns:

Type	Description
`Dict[str, Any]`	Updated vendor data

Raises:

Type	Description
`RezenError`	If the API request fails

`update_vendor_w9(vendor_id, w9_file)` ¶

Update a vendor's W9 file.

Parameters:

Name	Type	Description	Default
`vendor_id`	`str`	UUID of the vendor	required
`w9_file`	`BinaryIO`	W9 file to upload	required

Returns:

Type	Description
`Dict[str, Any]`	Updated vendor data

Raises:

Type	Description
`RezenError`	If the API request fails

Usage Examples¶

Directory Operations

Basic Contact SearchAdvanced Directory Search

from rezen import DirectoryClient

directory = DirectoryClient()

# Search for contacts
contacts = directory.search_contacts(name="John Doe")

for contact in contacts:
    print(f"Contact: {contact['name']} - {contact['email']}")

# Advanced search with multiple criteria
results = directory.advanced_search(
    name="Smith",
    location="California",
    agent_type="LISTING_AGENT"
)

Directory vs Main API¶

API Differences

Feature	Main API	Directory API
Endpoint	Standard ReZEN API	Specialized directory endpoint
Client	`RezenClient`	`DirectoryClient`
Purpose	Transaction management	Contact/agent discovery
Authentication	Same API key	Same API key

Combined Usage

You can use both clients together in your application:

from rezen import RezenClient, DirectoryClient

# Main client for transactions
client = RezenClient()

# Directory client for contact search
directory = DirectoryClient()

# Find contacts, then use in transactions
contacts = directory.search_contacts(name="John Doe")
if contacts:
    # Use contact info in transaction builder
    buyer_data = {
        "type": "BUYER",
        "first_name": contacts[0]['first_name'],
        "last_name": contacts[0]['last_name'],
        "email": contacts[0]['email']
    }
    # ... continue with transaction creation

Best Practices¶

Endpoint Considerations

The Directory API uses a different base URL than the main API
Ensure your API key has access to directory services
Consider rate limiting for directory searches

Production Usage

import logging
from rezen import DirectoryClient
from rezen.exceptions import RezenError

def safe_directory_search(name: str):
    """Safely search directory with error handling."""
    try:
        directory = DirectoryClient()
        results = directory.search_contacts(name=name)
        return {"success": True, "contacts": results}
    except RezenError as e:
        logging.error(f"Directory search failed: {e}")
        return {"success": False, "error": str(e)}

Next Steps¶

:material-account-tie: Agents API

Use agent data from directory in main API
:material-hammer-wrench: Transaction Builder

Add directory contacts to transactions
:material-rocket-launch: Getting Started

Complete setup guide for ReZEN clients

Directory API¶

Overview¶

Client Setup¶

Core Methods¶

Directory Client Operations¶

archive_person(person_id, archive=True) ¶

archive_vendor(vendor_id, archive=True) ¶

create_person(person_data, owner_agent_id=None, owner_team_id=None) ¶

create_vendor(vendor_data) ¶

get_permitted_roles(entry_type=None) ¶

get_person(person_id) ¶

get_vendor(vendor_id) ¶

get_vendor_w9_url(vendor_id) ¶

link_person(person_id, link_data) ¶

search_persons(page_number, page_size, is_archived=None, is_public=None, is_linked_to_vendor=None, search_text=None, first_name=None, last_name=None, email_address=None, phone_number=None, roles=None, sort_by=None) ¶

unlink_person(person_id) ¶

update_person(person_id, person_data) ¶

update_vendor(vendor_id, vendor_data) ¶

update_vendor_w9(vendor_id, w9_file) ¶

Usage Examples¶

Directory vs Main API¶

Best Practices¶

Next Steps¶

`archive_person(person_id, archive=True)` ¶

`archive_vendor(vendor_id, archive=True)` ¶

`create_person(person_data, owner_agent_id=None, owner_team_id=None)` ¶

`create_vendor(vendor_data)` ¶

`get_permitted_roles(entry_type=None)` ¶

`get_person(person_id)` ¶

`get_vendor(vendor_id)` ¶

`get_vendor_w9_url(vendor_id)` ¶

`link_person(person_id, link_data)` ¶

`search_persons(page_number, page_size, is_archived=None, is_public=None, is_linked_to_vendor=None, search_text=None, first_name=None, last_name=None, email_address=None, phone_number=None, roles=None, sort_by=None)` ¶

`unlink_person(person_id)` ¶

`update_person(person_id, person_data)` ¶

`update_vendor(vendor_id, vendor_data)` ¶

`update_vendor_w9(vendor_id, w9_file)` ¶