Agents API

Endpoints for managing agents and team members.

Agent Object

{
  "id": "agent_456def",
  "email": "sarah@agency.com",
  "name": "Sarah Martinez",
  "role": "agent",
  "status": "active",
  "profile": {
    "phone": "+1234567890",
    "photo": "https://cdn.propertybase.ai/...",
    "bio": "10+ years of experience...",
    "languages": ["en", "es"],
    "license_number": "RE-12345"
  },
  "team_id": "team_sales_a",
  "commission": {
    "tier": "senior",
    "rate": 0.03
  },
  "stats": {
    "active_leads": 25,
    "deals_closed": 12,
    "total_revenue": 1250000
  },
  "created_at": "2024-01-01T00:00:00Z",
  "last_active": "2024-01-25T14:30:00Z"
}

List Agents

GET /v1/agents

Query Parameters

Parameter	Type	Description
status	string	Filter by status (active, inactive)
role	string	Filter by role
team_id	string	Filter by team
search	string	Search by name or email

Example Request

curl -X GET "https://api.propertybase.ai/v1/agents?status=active&team_id=team_sales_a" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "agent_456def",
      "name": "Sarah Martinez",
      "email": "sarah@agency.com",
      "role": "agent",
      "status": "active",
      "stats": {
        "active_leads": 25,
        "deals_closed": 12
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 15
  }
}

Get Agent

GET /v1/agents/:id

Query Parameters

Parameter	Type	Description
expand	string	Include related data (team, leads)
include_stats	boolean	Include performance stats

Example Request

curl -X GET "https://api.propertybase.ai/v1/agents/agent_456def?include_stats=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Agent (Invite)

POST /v1/agents

Request Body

Field	Type	Required	Description
email	string	Yes	Agent's email
name	string	Yes	Full name
role	string	No	Role (default: agent)
team_id	string	No	Team assignment
commission	object	No	Commission settings

Example Request

curl -X POST "https://api.propertybase.ai/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@agency.com",
    "name": "John Doe",
    "role": "agent",
    "team_id": "team_sales_a",
    "commission": {
      "tier": "standard",
      "rate": 0.025
    }
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "agent_new789",
    "email": "john@agency.com",
    "name": "John Doe",
    "status": "invited",
    "invitation_sent_at": "2024-01-25T12:00:00Z"
  }
}

Update Agent

PUT /v1/agents/:id

Example Request

curl -X PUT "https://api.propertybase.ai/v1/agents/agent_456def" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team_sales_b",
    "commission": {
      "tier": "senior",
      "rate": 0.03
    }
  }'

Deactivate Agent

POST /v1/agents/:id/deactivate

Deactivates an agent without deleting their data.

Request Body

Field	Type	Description
reassign_leads_to	string	Agent ID to reassign leads
reason	string	Deactivation reason

Example Request

curl -X POST "https://api.propertybase.ai/v1/agents/agent_456def/deactivate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reassign_leads_to": "agent_123abc",
    "reason": "resignation"
  }'

Get Agent Stats

GET /v1/agents/:id/stats

Query Parameters

Parameter	Type	Description
period	string	Time period (week, month, quarter, year)
start_date	string	Custom start date
end_date	string	Custom end date

Example Response

{
  "success": true,
  "data": {
    "period": "month",
    "leads": {
      "assigned": 45,
      "contacted": 40,
      "qualified": 25,
      "closed": 8
    },
    "conversion_rate": 0.178,
    "average_response_time": "2h 15m",
    "revenue": {
      "closed": 1250000,
      "pending": 500000,
      "currency": "USD"
    },
    "commission_earned": 37500
  }
}

Get Agent Leads

GET /v1/agents/:id/leads

Returns leads assigned to the agent.

Example Request

curl -X GET "https://api.propertybase.ai/v1/agents/agent_456def/leads?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

Agent Roles

Role	Description
owner	Workspace owner
admin	Administrator
agent	Sales agent
viewer	Read-only access

Agent Status

Status	Description
invited	Invitation sent, not accepted
active	Active and can work
inactive	Deactivated