# Collections

> Keep a named list of homes from any source with colleagues and agents from other agencies.

A collection is a named list of homes you keep with other agents. It can hold homes from any source your agency can open: the Fondaro network, your connected feeds and property sites.

These routes take a signed-in dashboard session with an active organization (`Authorization: Bearer <session token>`); a property API key is refused. A collection you are not in answers `404`, whether or not it exists.

**Who can do what.** You create a collection in your active agency and manage it: rename, delete, add and remove people. You can add a colleague or someone you have an accepted conversation with, never someone you blocked or who blocked you. Everyone in it can add and remove homes, and anyone but the creator can leave.

**What each person sees.** Each person sees every home through their own agency. Another agency's home shows while it is on the market, with its address and map position, never with the owner's private commission. A home you can no longer open (sold, withdrawn, or from a source your agency has not connected) stays in the list with `listing: null`.

## List and create

### `GET /network/collections`

The collections you are in, most recently changed first.

```bash
curl https://api.fondaro.com/network/collections \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

```json
{
  "collections": [
    {
      "id": "5f0c2d8e-3b1a-4c7e-9a42-6d8e1f0b7c21",
      "name": "Golf frontline, three bedrooms",
      "itemCount": 6,
      "memberCount": 3,
      "isCreator": true,
      "createdAt": "2026-09-24T08:00:00.000Z",
      "updatedAt": "2026-09-24T09:12:00.000Z"
    }
  ]
}
```

### `POST /network/collections`

| Field | Rules |
|---|---|
| `name` | Required, up to 80 characters |

```bash
curl -X POST https://api.fondaro.com/network/collections \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Golf frontline, three bedrooms"}'
```

Returns the new collection's summary, with you as its first member.

## Read one

### `GET /network/collections/:id`

The collection, its people and its homes (newest first).

```json
{
  "id": "5f0c2d8e-3b1a-4c7e-9a42-6d8e1f0b7c21",
  "name": "Golf frontline, three bedrooms",
  "itemCount": 2,
  "memberCount": 2,
  "isCreator": true,
  "members": [
    { "clerkUserId": "user_2abc", "firstName": "Lucia", "lastName": "Moreno", "imageUrl": null, "isCreator": true }
  ],
  "items": [
    {
      "id": "b7e1a2c4-0f3d-4e59-8a61-2c9d7e0f1a33",
      "ref": { "source": "internal", "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" },
      "addedByUserId": "user_2def",
      "createdAt": "2026-09-24T09:12:00.000Z",
      "listing": { "title": "Garden apartment", "price": 650000, "currency": "EUR", "bedrooms": 3, "city": "Marbella", "sharedCommission": 3 }
    },
    {
      "id": "0c4f9e2a-7d1b-4a38-b5e6-3f2a1c0d9e84",
      "ref": { "source": "resales_online", "id": "R4471123", "country": "ES" },
      "addedByUserId": "user_2abc",
      "createdAt": "2026-09-24T08:05:00.000Z",
      "listing": null
    }
  ]
}
```

`addedByUserId` is `null` when that person has deleted their account.

### `PATCH /network/collections/:id`

Renames it (`{ "name": "..." }`). Creator only.

### `DELETE /network/collections/:id`

Deletes it and its homes. Creator only. Answers `204`.

## Add and remove homes

### `POST /network/collections/:id/items`

| Field | Rules |
|---|---|
| `ref` | The home's `{ source, id, country? }` exactly as [Property sources](https://www.fondaro.com/docs/api/properties/sources.md) returned it |

```bash
curl -X POST https://api.fondaro.com/network/collections/5f0c2d8e-3b1a-4c7e-9a42-6d8e1f0b7c21/items \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":{"source":"resales_online","id":"R4471123","country":"ES"}}'
```

Your agency must be able to open the home now, and it must be on the market. Adding a home twice returns the same item.

### `DELETE /network/collections/:id/items/:itemId`

Answers `204`, also when the home was already gone.

## Add and remove people

### `POST /network/collections/:id/members`

| Field | Rules |
|---|---|
| `clerkUserId` | A colleague, or a connection from `GET /network/connections` |

Returns the person as the collection shows them. Adding someone twice changes nothing. Creator only.

### `DELETE /network/collections/:id/members/:userId`

Removes someone (creator), or leaves when `userId` is your own. The creator cannot leave; delete the collection instead. Answers `204`.

## Errors and limits

| Status | Code | When |
|---|---|---|
| `400` | `LISTING_COLLECTION_CREATOR_CANNOT_LEAVE` | The creator tried to leave |
| `403` | `LISTING_COLLECTION_CREATOR_ONLY` | Renaming, deleting or managing people when you did not create it |
| `403` | `LISTING_COLLECTION_ORGANIZATION_REQUIRED` | Your active organization is not an agency you belong to |
| `404` | `LISTING_COLLECTION_NOT_FOUND` | No such collection, or you are not in it |
| `422` | `LISTING_COLLECTION_LISTING_UNREADABLE` | Your agency cannot open the home, or it is off the market |
| `422` | `LISTING_COLLECTION_MEMBER_NOT_CONNECTED` | Not a colleague or connection, blocked, or not on the network |
| `422` | `LISTING_COLLECTION_LIMIT_REACHED`, `LISTING_COLLECTION_ITEMS_FULL`, `LISTING_COLLECTION_MEMBERS_FULL` | A limit below is reached |

| Limit | Value |
|---|---|
| Name | 80 characters |
| Homes in one collection | 200 |
| People in one collection, you included | 50 |
| Collections you can create | 100 |

Source: https://www.fondaro.com/docs/api/listing-collections