Agents

Manage real estate agent profiles for your organization. Agents can be linked to Clerk user accounts (team members) or created as standalone profiles.

Create a Clerk-Linked Agent

Authentication: Required (JWT)

Creates an agent profile linked to an existing Clerk organization member.

Request Body

| Field | Type | Required | Description | Constraints | |-------|------|----------|-------------|-------------| | clerkUserId | string | Yes | Clerk user ID to link | Non-empty | | firstName | string | No | First name | Max 100 chars | | lastName | string | No | Last name | Max 100 chars | | avatarUrl | string | No | Avatar image URL | Max 500 chars | | displayEmail | string | No | Public-facing email | Valid email format | | phoneNumber | string | No | Phone number | — | | whatsappNumber | string | No | WhatsApp number | — | | description | string | No | Agent bio / description | — | | title | string | No | Job title | — | | isActive | boolean | No | Whether the agent is active | Default: true | | additionalInfo | object | No | Custom key-value data | — |

Example

curl -X POST https://api.leadhql.com/agents \
  -H "Authorization: Bearer <jwt-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "clerkUserId": "user_2abc123def456",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "displayEmail": "sarah@luxuryestates.com",
    "phoneNumber": "+34612345678",
    "title": "Senior Property Consultant"
  }'

Create a Standalone Agent

Authentication: Required (JWT)

Creates an agent profile that is not linked to a Clerk user account. Use this for external agents or collaborators who don't have a LeadHQL login.

Request Body

| Field | Type | Required | Description | Constraints | |-------|------|----------|-------------|-------------| | firstName | string | Yes | First name | Max 100 chars, non-empty | | lastName | string | No | Last name | Max 100 chars | | displayEmail | string | No | Public email | Valid email format | | phoneNumber | string | No | Phone number | — | | whatsappNumber | string | No | WhatsApp number | — | | description | string | No | Agent bio | — | | title | string | No | Job title | — | | isActive | boolean | No | Active status | Default: true | | additionalInfo | object | No | Custom data | — |

Example

curl -X POST https://api.leadhql.com/agents/standalone \
  -H "Authorization: Bearer <jwt-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Miguel",
    "lastName": "Fernández",
    "displayEmail": "miguel@example.com",
    "phoneNumber": "+34698765432",
    "title": "Independent Agent"
  }'

List Agents

Authentication: Required (JWT)

Returns all agents for your organization.

Query Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | isActive | boolean | — | Filter by active status | | search | string | — | Search by name | | includeClerkMembers | boolean | false | Include Clerk members that don't yet have agent records |

Example

curl "https://api.leadhql.com/agents?isActive=true&search=sarah" \
  -H "Authorization: Bearer <jwt-session-token>"

Get an Agent

Authentication: Required (JWT)

Example

curl https://api.leadhql.com/agents/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer <jwt-session-token>"

Errors

| Status | Condition | |--------|-----------| | 404 | Agent not found |

Update an Agent

Authentication: Required (JWT)

All fields are optional — include only what you want to change.

Request Body

| Field | Type | Description | Constraints | |-------|------|-------------|-------------| | firstName | string | First name | Max 100 chars | | lastName | string | Last name | Max 100 chars | | avatarUrl | string | Avatar URL | Max 500 chars | | avatarThumbnailUrl | string | Thumbnail URL | Max 500 chars | | displayEmail | string | Public email | Valid email | | phoneNumber | string | Phone number | — | | whatsappNumber | string | WhatsApp number | — | | description | string | Bio / description | — | | title | string | Job title | — | | isActive | boolean | Active status | — | | additionalInfo | object | Custom data | — |

Example

curl -X PUT https://api.leadhql.com/agents/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer <jwt-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Director of Sales",
    "description": "Specializing in luxury beachfront properties on the Costa del Sol."
  }'

Delete an Agent

Authentication: Required (JWT)

Example

curl -X DELETE https://api.leadhql.com/agents/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer <jwt-session-token>"

Response

{
  "success": true
}

Upload Agent Avatar

Authentication: Required (JWT)

Upload a profile photo for an agent. The image is resized and stored, and the agent record is updated with the new URLs.

Request

Send the file as multipart/form-data with the field name avatar.

| Constraint | Value | |-----------|-------| | Max file size | 5 MB | | Accepted formats | JPEG, JPG, PNG, WebP, GIF |

Example

curl -X POST https://api.leadhql.com/agents/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/avatar \
  -H "Authorization: Bearer <jwt-session-token>" \
  -F "avatar=@photo.jpg"

Response

Returns the updated agent object with new avatarUrl and avatarThumbnailUrl fields.

Errors

| Status | Condition | |--------|-----------| | 404 | Agent not found | | 422 | File too large or invalid format |

Delete Agent Avatar

Authentication: Required (JWT)

Removes the agent's avatar photo.

Example

curl -X DELETE https://api.leadhql.com/agents/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/avatar \
  -H "Authorization: Bearer <jwt-session-token>"

Public: Active Agents with Listings

Authentication: None required (public endpoint)

Returns active agents that have at least one active property listing. This is intended for public-facing websites to display agent directories.

Query Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | organizationId | UUID | Yes | Organization ID to list agents for |

Example

curl "https://api.leadhql.com/properties/agents?organizationId=a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"

Response

Returns an array of public agent profiles (no internal IDs or timestamps):

[
  {
    "id": "f1e2d3c4-...",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "avatarUrl": "https://cdn.leadhql.com/avatars/...",
    "avatarThumbnailUrl": "https://cdn.leadhql.com/avatars/...",
    "displayEmail": "sarah@luxuryestates.com",
    "phoneNumber": "+34612345678",
    "whatsappNumber": "+34612345678",
    "description": "Specializing in luxury beachfront properties.",
    "title": "Senior Property Consultant"
  }
]

Response Format Note

Agent responses include both snake_case and camelCase field names for backwards compatibility:

• first_name / firstName
• last_name / lastName
• image_url / avatarUrl

Prefer the camelCase versions in new integrations. The public endpoint only returns camelCase fields.