# Co-listers

> Invite agents and agencies from other agencies to co-list or refer a home, answer invitations, and claim an external listing.

A co-lister is another agency, or one of its agents, working a home beside the agency that lists it. These routes invite them, answer invitations and end the arrangement.

They take a signed-in dashboard session with an active organization (`Authorization: Bearer <session token>`); a property API key is refused.

| Role | Meaning |
|---|---|
| `co_lister` | Markets the home beside the listing agency: shown on the home's detail, listed under the co-lister's own listings, may host an open house on it and be messaged about it |
| `referrer` | Brought the home to the listing agency; visible to the two agencies only |
| `lister` | Your agency's verified claim to an external home (one read with your agency's own credentials), so you can invite co-listers to it |

Your agency's admin or the home's listing agent invites. An invited agent answers for themselves; a whole-agency invitation is answered by that agency's admin. Either side can end it. Nothing here carries the owner's private commission, and a home off the market is never shown to another agency.

## List a home's collaborators

### `GET /network/collaborators`

| Query | Meaning |
|---|---|
| `listingSource`, `listingId` | Required: the home's `ref` |
| `listingCountry` | The `ref.country`, when it has one |

```bash
curl "https://api.fondaro.com/network/collaborators?listingSource=internal&listingId=a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

```json
{
  "canManage": true,
  "collaborators": [
    {
      "id": "8d2f4c1a-6b3e-4f70-9a15-2e7c0b9d4f36",
      "ref": { "source": "internal", "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" },
      "role": "co_lister",
      "status": "active",
      "agency": { "networkSlug": "costa-homes", "name": "Costa Homes", "organizationId": "2c7e0b9d-4f36-4a15-8d2f-4c1a6b3e4f70" },
      "person": { "clerkUserId": "user_2def", "firstName": "Tom", "lastName": "Berg", "imageUrl": null, "title": "Sales agent" },
      "canRespond": false,
      "canRevoke": true,
      "createdAt": "2026-09-24T08:00:00.000Z",
      "respondedAt": "2026-09-24T09:30:00.000Z"
    }
  ]
}
```

Pending and active collaborators. `person` is `null` when a whole agency collaborates. Only the listing agency's agents can read this; anyone else gets `404`.

## Invite

### `POST /network/collaborators`

| Field | Rules |
|---|---|
| `ref` | Required: the home's `{ source, id, country? }` |
| `role` | Required: `co_lister` or `referrer` |
| `handle` | An agent's network handle |
| `organizationId` or `networkSlug` | The agency: alone to invite the whole agency, or with `handle` when the agent works at several |

```bash
curl -X POST https://api.fondaro.com/network/collaborators \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":{"source":"internal","id":"a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"},"role":"co_lister","handle":"tom-berg"}'
```

Returns the collaborator with `"status": "pending"`, and the invited agent (or the agency's admins) get a `network.colisting_request` push. The home must be on the market. Blocked people, suspended profiles, disabled agencies and people who left their agency all look the same: no one by that name.

## Answer or end

### `POST /network/collaborators/:id/accept`, `/decline`, `/revoke`

`accept` and `decline` are for the invitee; `revoke` is for either side. Each returns the collaborator with its new `status` (`active`, `declined` or `revoked`).

```bash
curl -X POST https://api.fondaro.com/network/collaborators/8d2f4c1a-6b3e-4f70-9a15-2e7c0b9d4f36/accept \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

### `GET /network/collaborators/invitations`

Pending invitations to you or your active agency. Each carries the collaborator fields, `invitedBy` (the inviting agency), `listing` (the home as your agency sees it, or `null` when off the market) and `canRespond`.

## Claim an external home

### `POST /network/collaborators/claims`

Admin only. Claims `lister` on a home from one of your connected feeds, so you can invite co-listers to it.

```bash
curl -X POST https://api.fondaro.com/network/collaborators/claims \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":{"source":"zoddak","id":"12345"}}'
```

The claim holds only when your agency's own access to the source returns the home as one of your listings. Property sites never can, and a Fondaro network home already has its listing agency. Claiming again returns the same claim; ending it also ends the invitations made under it.

## Where co-listing shows

- `GET /properties/:id` from a dashboard session carries `coListers`, one card per active co-lister. Contact details appear only when the agent shares them with the network.
- A dashboard session's `POST /properties/search` with `"scope": "own"` also returns the homes you co-list (on the market only), marked `relation: "co_lister"`.
- `POST /chat/dms/from-record` with `agentUserId` messages one of a home's co-listers instead of its listing agent.
- An active co-lister may host an [open house](https://www.fondaro.com/docs/api/open-houses.md) on the home.

## Errors and limits

| Status | Code | When |
|---|---|---|
| `400` | `LISTING_COLLABORATOR_OWN_AGENCY` | You invited your own agency |
| `400` | `LISTING_COLLABORATOR_AGENCY_REQUIRED` | The agent works at several agencies; name one |
| `403` | `LISTING_COLLABORATOR_MANAGER_ONLY` | Not the admin or the listing agent |
| `403` | `LISTING_COLLABORATOR_INVITEE_ONLY` | Only the invitee answers |
| `404` | `LISTING_COLLABORATOR_NOT_FOUND` | Missing, or not yours to see |
| `404` | `LISTING_COLLABORATOR_INVITEE_UNAVAILABLE` | No agent or agency by that name can be invited |
| `409` | `LISTING_COLLABORATOR_DUPLICATE` | Already invited or active in that role |
| `409` | `LISTING_COLLABORATOR_LIMIT_REACHED` | The home has 20 pending and active collaborators |
| `409` | `LISTING_COLLABORATOR_CLOSED` | Already answered or ended |
| `422` | `LISTING_COLLABORATOR_LISTING_UNAVAILABLE` | Your agency does not list the home, or it is off the market |
| `422` | `LISTING_COLLABORATOR_CLAIM_UNSUPPORTED`, `LISTING_COLLABORATOR_CLAIM_UNVERIFIED`, `LISTING_COLLABORATOR_CLAIM_INTERNAL` | The claim cannot be proved, was not confirmed, or is on a Fondaro network home |

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