Agents

The Agents API manages your organization's roster: the agent cards shown on your listings, brochures and website. A listing's agentId is an agent id from this roster.

These endpoints take a signed-in member's session token (Authorization: Bearer <session-token>); API keys do not open them. See Authentication.

How the roster works

• Every member has a card. Each member of your organization gets one agent card automatically when they join. Leaving deactivates it and keeps its data; rejoining reactivates it. A person in three organizations has three cards, one per organization.
• Name and photo belong to the person. On a member's card, firstName, lastName and the photo come from their Fondaro account. Changing them here changes the account, so it shows in every organization they belong to. Only an organization admin or the member themselves may do this.
• Everything else belongs to the organization. title, displayEmail, phoneNumber, whatsappNumber, description, isActive and additionalInfo are stored on this card only.
• Standalone cards are for someone without a Fondaro login, such as an outside collaborator. Your organization owns them entirely.
• Agents are identified by id, a UUID. It is the only agent identifier any endpoint accepts.

The agent object

Responses also carry first_name, last_name and image_url, older spellings of firstName, lastName and avatarUrl. Use the camelCase fields.

List agents

GET /agents

Returns every card in your organization as an array.

curl "https://api.fondaro.com/agents?search=ana" \  -H "Authorization: Bearer $SESSION_TOKEN"

[  {    "id": "6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b",    "organizationId": "0b8e3f4a-1c2d-4e5f-8a9b-0c1d2e3f4a5b",    "clerkUserId": "user_2abcDEF",    "isClerkLinked": true,    "firstName": "Ana",    "lastName": "García",    "avatarUrl": "https://…/avatar.jpg",    "displayEmail": "ana@agency.example",    "phoneNumber": "+34 600 000 000",    "title": "Senior agent",    "isActive": true,    "shareContactOnNetwork": false  }]

Get an agent

GET /agents/:id

Returns one card. An id from another organization answers 404.

curl https://api.fondaro.com/agents/6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b \  -H "Authorization: Bearer $SESSION_TOKEN"

{ "id": "6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b", "firstName": "Ana", "lastName": "García", "title": "Senior agent", "isActive": true }

Create a standalone agent

POST /agents/standalone

Creates a card for someone without a Fondaro login. Members get their card automatically, so there is no endpoint to create one for them.

curl -X POST https://api.fondaro.com/agents/standalone \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"firstName": "Miguel", "lastName": "Fernández", "displayEmail": "miguel@example.com", "title": "Independent agent"}'

{ "id": "a1b2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d", "clerkUserId": null, "isClerkLinked": false, "firstName": "Miguel", "lastName": "Fernández", "isActive": true }

Update an agent

PUT /agents/:id

Changes only the fields you send. On a member's card, firstName, lastName, avatarUrl and shareContactOnNetwork may be changed only by an admin or that member (403 with code: "ORG_ADMIN_OR_SELF_REQUIRED" otherwise).

curl -X PUT https://api.fondaro.com/agents/6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"title": "Sales director", "description": "Twelve years selling villas on the Golden Mile."}'

{ "id": "6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b", "title": "Sales director", "description": "Twelve years selling villas on the Golden Mile." }

Set the public contact address

PUT /agents/:id/from-email

Admins only. Sets displayEmail, or clears it with null. Email is still sent from the person's connected inbox, not this address.

curl -X PUT https://api.fondaro.com/agents/6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b/from-email \  -H "Authorization: Bearer $SESSION_TOKEN" \  -H "Content-Type: application/json" \  -d '{"displayEmail": "ana@youragency.com"}'

{ "id": "6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b", "displayEmail": "ana@youragency.com" }

Upload or remove a photo

POST /agents/:id/avatar

Uploads a photo as multipart/form-data in the avatar field: JPEG, PNG, WebP or GIF, up to 5 MB. On a member's card the photo becomes their account photo (admins and the member only). Returns the updated agent.

curl -X POST https://api.fondaro.com/agents/6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b/avatar \  -H "Authorization: Bearer $SESSION_TOKEN" \  -F "avatar=@photo.jpg"

{ "id": "6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b", "avatarUrl": "https://…", "avatarThumbnailUrl": "https://…" }

DELETE /agents/:id/avatar removes the photo and returns the updated agent.

Deactivate an agent

DELETE /agents/:id

Sets the card to inactive (isActive: false). Its data stays, and listings that name it keep the reference.

curl -X DELETE https://api.fondaro.com/agents/a1b2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d \  -H "Authorization: Bearer $SESSION_TOKEN"

{ "success": true }

Errors