Agents API

The Agents API provides endpoints for listing, creating, and managing real estate agent profiles.

List Agents

Get a paginated list of agents.

GET /api/admin/agents

Auth Required

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`page_size`	integer	Items per page (default: 20, max: 100)
`brokerage_id`	integer	Filter by brokerage
`status`	string	Filter by status (active, inactive)
`search`	string	Search by name or email

Example Request

curl -H "X-API-Key: idx_your_key" \
     "https://api.your-domain.com/api/admin/agents?brokerage_id=1&status=active"

Response

{
  "items": [
    {
      "id": 45,
      "broker_id": 1,
      "name": "Jane Smith",
      "slug": "jane-smith",
      "email": "jane@example.com",
      "phone": "208-555-0123",
      "bio": "Specializing in residential properties...",
      "photo_url": "/uploads/agents/jane-smith.jpg",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 25,
  "page": 1,
  "page_size": 20,
  "total_pages": 2
}

Get Agent by ID

Retrieve a specific agent’s details.

GET /api/admin/agents/{agent_id}

Auth Required

Path Parameters

Parameter	Type	Description
`agent_id`	integer	Agent’s unique ID

Response

{
  "id": 45,
  "broker_id": 1,
  "brokerage": {
    "id": 1,
    "name": "Sample Realty Co.",
    "slug": "sample-realty"
  },
  "name": "Jane Smith",
  "slug": "jane-smith",
  "email": "jane@example.com",
  "phone": "208-555-0123",
  "bio": "With over 10 years of experience in the Magic Valley...",
  "photo_url": "/uploads/agents/jane-smith.jpg",
  "status": "active",
  "specialties": ["Residential", "First-Time Buyers", "Relocation"],
  "social_links": {
    "facebook": "https://facebook.com/janesmith",
    "instagram": "https://instagram.com/janesmithrealty"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-12-20T14:22:00Z"
}

Create Agent

Create a new agent profile.

POST /api/admin/agents

Broker/Admin Only

Request Body

{
  "brokerage_id": 1,
  "name": "John Doe",
  "slug": "john-doe",
  "email": "john@example.com",
  "phone": "208-555-0456",
  "bio": "New agent specializing in...",
  "status": "active"
}

Field	Type	Required	Description
`brokerage_id`	integer	Yes	Parent brokerage ID
`name`	string	Yes	Agent’s full name
`slug`	string	Yes	URL-friendly identifier
`email`	string	Yes	Contact email
`phone`	string	No	Contact phone
`bio`	string	No	Agent biography
`status`	string	No	active or inactive (default: active)

Response

{
  "id": 46,
  "broker_id": 1,
  "name": "John Doe",
  "slug": "john-doe",
  "email": "john@example.com",
  "status": "active",
  "created_at": "2024-12-28T10:00:00Z"
}

Update Agent

Update an existing agent’s profile.

PUT /api/admin/agents/{agent_id}

Broker/Admin Only

Request Body

{
  "bio": "Updated biography text...",
  "phone": "208-555-9999",
  "status": "active"
}

All fields are optional. Only provided fields are updated.

Response

Returns the updated agent object.

Delete Agent

Soft-delete an agent (sets disabled_at).

DELETE /api/admin/agents/{agent_id}

Admin Only

Response

{
  "message": "Agent deleted successfully",
  "id": 46
}

Search Agents

Semantic search for agents by expertise and bio.

GET /api/admin/search/agents?q=first+time+buyers

Auth Required

Query Parameters

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

Response

{
  "query": "first time buyers",
  "results": [
    {
      "id": 45,
      "name": "Jane Smith",
      "brokerage": "Sample Realty Co.",
      "bio": "Specializing in helping first-time buyers...",
      "similarity": 0.87
    }
  ],
  "total": 5
}

Public Agent Endpoints

These endpoints are publicly accessible without authentication.

List Public Agents

GET /api/public/agents

Parameter	Type	Description
`brokerage_id`	integer	Filter by brokerage

Get Agent by Slug

GET /api/public/agents/{slug}

Returns public-facing agent information suitable for website display.

Upload Agent Photo

Upload and optimize an agent’s profile photo.

POST /api/upload/agent-photo

Auth Required

Request

Multipart form data:

Field	Type	Description
`file`	file	Image file (JPEG, PNG, WebP)
`agent_id`	integer	Agent to update

Response

{
  "success": true,
  "photo_url": "/uploads/agents/jane-smith.jpg",
  "thumbnail_url": "/uploads/agents/jane-smith-thumb.jpg"
}

Error Responses

Agent Not Found

{
  "detail": "Agent not found"
}

Status: 404 Not Found

Duplicate Slug

{
  "detail": "Agent with slug 'john-doe' already exists"
}

Status: 400 Bad Request

Permission Denied

{
  "detail": "Cannot create agent for another brokerage"
}

Status: 403 Forbidden