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

POST /agents

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.fondaro.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

POST /agents/standalone

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 Fondaro 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.fondaro.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

GET /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.fondaro.com/agents?isActive=true&search=sarah" \
  -H "Authorization: Bearer <jwt-session-token>"

Get an Agent

GET /agents/:id

Authentication: Required (JWT)

Example

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

Errors

Status	Condition
`404`	Agent not found

Update an Agent

PUT /agents/:id

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.fondaro.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

DELETE /agents/:id

Authentication: Required (JWT)

Example

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

Response

{
  "success": true
}

Upload Agent Avatar

POST /agents/:id/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.fondaro.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

DELETE /agents/:id/avatar

Authentication: Required (JWT)

Removes the agent's avatar photo.

Example

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

Public: Active Agents with Listings

GET /properties/agents?organizationId=<uuid>

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.fondaro.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.fondaro.com/avatars/...",
    "avatarThumbnailUrl": "https://cdn.fondaro.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.

Agents

Create a Clerk-Linked Agent

Request Body

Example

Create a Standalone Agent

Request Body

Example

List Agents

Query Parameters

Example

Get an Agent

Example

Errors

Update an Agent

Request Body

Example

Delete an Agent

Example

Response

Upload Agent Avatar

Request

Example

Response

Errors

Delete Agent Avatar

Example

Public: Active Agents with Listings

Query Parameters

Example

Response

Response Format Note

Related Articles

Fondaro Help

Hi there, how can we help?