Brokerages API

The Brokerages API provides endpoints for managing real estate brokerage firms, including their branding, feature flags, and associated contacts.

List Brokerages

Get a paginated list of brokerages.

GET /api/admin/brokerages

Auth Required

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`page_size`	integer	Items per page (default: 20, max: 100)

Example Request

curl -H "X-API-Key: idx_your_key" \
     "https://api.your-domain.com/api/admin/brokerages?page=1&page_size=10"

Response

{
  "items": [
    {
      "id": 1,
      "slug": "sample-realty",
      "name": "Sample Realty Co.",
      "tagline": "Your trusted real estate partner",
      "description": "Full-service brokerage in the Magic Valley...",
      "address_city": "Twin Falls",
      "address_state": "Idaho",
      "address_state_abbr": "ID",
      "feature_semantic_search": true,
      "feature_map_search": true,
      "logo_url": "/uploads/brokerages/sample-logo.png",
      "primary_color": "#2563eb",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "page_size": 10,
  "total_pages": 1
}

Get Brokerage by ID

Retrieve a specific brokerage’s details.

GET /api/admin/brokerages/{brokerage_id}

Auth Required

Path Parameters

Parameter	Type	Description
`brokerage_id`	integer	Brokerage’s unique ID

Response

{
  "id": 1,
  "slug": "sample-realty",
  "name": "Sample Realty Co.",
  "tagline": "Your trusted real estate partner",
  "description": "Full-service brokerage...",
  "address_street": "123 Blue Lakes Blvd",
  "address_city": "Twin Falls",
  "address_state": "Idaho",
  "address_state_abbr": "ID",
  "address_zip": "83301",
  "address_country": "US",
  "map_center_lat": 42.5569,
  "map_center_lng": -114.4602,
  "map_zoom": 12,
  "map_bounds_north": 43.5,
  "map_bounds_south": 42.0,
  "map_bounds_east": -113.5,
  "map_bounds_west": -115.5,
  "feature_semantic_search": true,
  "feature_map_search": true,
  "feature_favorites": true,
  "feature_contact_form": true,
  "feature_virtual_tours": false,
  "feature_mortgage_calculator": true,
  "license_type": "Real Estate Brokerage",
  "license_number": "DB-12345",
  "logo_url": "/uploads/brokerages/sample-logo.png",
  "primary_color": "#2563eb",
  "social_facebook": "https://facebook.com/your-brokerage",
  "social_instagram": "https://instagram.com/your-brokerage",
  "franchise_affiliation": null,
  "va_loans": true,
  "military_specialist": true,
  "website": "https://www.your-domain.com",
  "hero_headline": "Find Your Dream Home in Idaho",
  "hero_subtitle": "Search thousands of listings with natural language search",
  "hero_search_examples": [
    "modern kitchen with granite",
    "large backyard near schools",
    "mountain views"
  ],
  "nav_main": [...],
  "nav_footer": [...],
  "disabled_at": null,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-12-20T14:22:00Z"
}

Create Brokerage

Create a new brokerage.

POST /api/admin/brokerages

Admin Only

Request Body

{
  "slug": "new-realty",
  "name": "New Realty Group",
  "tagline": "Your trusted partner in real estate",
  "address_city": "Boise",
  "address_state_abbr": "ID",
  "feature_semantic_search": true,
  "feature_map_search": true,
  "primary_color": "#059669"
}

Required Fields

Field	Type	Description
`slug`	string	URL-friendly unique identifier
`name`	string	Brokerage display name

Optional Fields

Field	Type	Description
`address_street`	string	Street address
`address_city`	string	City
`address_state`	string	Full state name
`address_state_abbr`	string	State abbreviation
`address_zip`	string	ZIP code
`address_country`	string	Country (default: US)

Field	Type	Description
`map_center_lat`	number	Default map center latitude
`map_center_lng`	number	Default map center longitude
`map_zoom`	integer	Default zoom level
`map_bounds_*`	number	Bounding box (north, south, east, west)

Field	Type	Default
`feature_semantic_search`	boolean	true
`feature_map_search`	boolean	true
`feature_favorites`	boolean	true
`feature_contact_form`	boolean	true
`feature_virtual_tours`	boolean	false
`feature_mortgage_calculator`	boolean	true

Field	Type	Description
`tagline`	string	Short tagline
`description`	string	Full description
`logo_url`	string	Logo image URL
`primary_color`	string	Hex color code
`hero_headline`	string	Homepage headline
`hero_subtitle`	string	Homepage subtitle
`hero_search_examples`	array	Example search queries

Response

Returns the created brokerage object.

Update Brokerage

Update an existing brokerage.

PUT /api/admin/brokerages/{brokerage_id}

Admin Only

Request Body

{
  "tagline": "Updated tagline",
  "primary_color": "#dc2626",
  "feature_virtual_tours": true
}

All fields are optional. Only provided fields are updated.

Response

Returns the updated brokerage object.

Delete Brokerage

Soft-delete a brokerage (sets disabled_at).

DELETE /api/admin/brokerages/{brokerage_id}

Admin Only

Response

{
  "message": "Brokerage deleted successfully"
}

Search Brokerages

Semantic search for brokerages by specialties and services.

GET /api/admin/search/brokerages?q=military+relocation

Auth Required

Query Parameters

Parameter	Type	Description
`q`	string	Search query (min 2 chars)
`limit`	integer	Max results (default: 10, max: 50)

Example Queries

"military relocation specialist"
"RE/MAX franchise"
"VA loan expert in Boise"

Response

{
  "query": "military relocation",
  "results": [
    {
      "id": 1,
      "slug": "sample-realty",
      "name": "Sample Realty Co.",
      "tagline": "Your trusted real estate partner",
      "military_specialist": true,
      "va_loans": true,
      "franchise_affiliation": null,
      "logo_url": "/uploads/brokerages/sample-logo.png",
      "similarity": 0.89
    }
  ],
  "total": 3
}

Broker Contacts

Broker contacts are the licensed individuals associated with a brokerage who can be contacted for business purposes.

List Broker Contacts

GET /api/admin/broker-contacts

Auth Required

Parameter	Type	Description
`brokerage_id`	integer	Filter by brokerage
`page`	integer	Page number (default: 1)
`page_size`	integer	Items per page (default: 20)

Response

{
  "items": [
    {
      "id": 12,
      "brokerage_id": 1,
      "name": "John Broker",
      "email": "john@example.com",
      "phone": "+12085550123",
      "phone_display": "(208) 555-0123",
      "license_type": "Designated Broker",
      "license_number": "DB-12345",
      "is_primary": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "page_size": 20,
  "total_pages": 1
}

Get Broker Contact

GET /api/admin/broker-contacts/{contact_id}

Create Broker Contact

POST /api/admin/broker-contacts

Broker/Admin Only

{
  "brokerage_id": 1,
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+12085550456",
  "license_type": "Associate Broker",
  "license_number": "AB-67890",
  "is_primary": false
}

Update Broker Contact

PUT /api/admin/broker-contacts/{contact_id}

Broker/Admin Only

Delete Broker Contact

DELETE /api/admin/broker-contacts/{contact_id}

Admin Only

Search Broker Contacts

GET /api/admin/search/broker-contacts?q=designated+broker

Parameter	Type	Description
`q`	string	Search query
`brokerage_id`	integer	Filter by brokerage
`limit`	integer	Max results (default: 10)

Public Brokerage Endpoints

These endpoints are publicly accessible without authentication.

Get Public Brokerage Info

GET /api/public/brokerage

Returns the brokerage associated with the current domain (based on Host header).

Response

{
  "id": 1,
  "name": "Sample Realty Co.",
  "tagline": "Your trusted real estate partner",
  "logo_url": "/uploads/brokerages/sample-logo.png",
  "primary_color": "#2563eb",
  "address_city": "Twin Falls",
  "address_state_abbr": "ID",
  "social_facebook": "https://facebook.com/your-brokerage",
  "social_instagram": "https://instagram.com/your-brokerage"
}

Error Responses

Brokerage Not Found

{
  "detail": "Brokerage not found"
}

Status: 404 Not Found

Duplicate Slug

{
  "detail": "Slug already exists"
}

Status: 400 Bad Request

Search Service Unavailable

{
  "detail": "Search service unavailable: connection refused"
}

Status: 503 Service Unavailable