# Own-listing lifecycle

> How your listings move between statuses, expire and renew, and how imports and history are recorded.

A listing you own moves through a small set of statuses, expires two months after it is renewed, and keeps a history of every change. These endpoints use the same `/properties` routes and scopes as [Create and update listings](https://www.fondaro.com/docs/api/properties/crud.md).

## Statuses

`active` · `inactive` · `pending` · `sold` · `rented` · `deleted`

| Event | Status |
|---|---|
| `POST /properties` | Always `pending` until Fondaro makes it `active` |
| `PUT /properties/:id` without `status` | Unchanged, including `active` |
| A listing reaches `expiresAt` | `active` becomes `inactive` (unless it renews automatically) |
| `PUT /properties/:id/renew` | `inactive` becomes `active` again |
| `PUT /properties/:id` with `status` | `sold`, `rented` or `deleted` |
| `DELETE /properties/:id` | `deleted` |
| First Resales Online import | `active`, because it is already public there |

There is no API route that returns a sold, rented or deleted listing to active.

## Change status

### `PUT /properties/:id`

Send `status` alone to close a listing. `sold` and `rented` mark the outcome; `deleted` removes it from search and feeds while keeping its history. Re-sending the current status changes nothing; any other value is a `400`.

```bash
curl -X PUT https://api.fondaro.com/properties/29a1e184-237a-40c8-a1fe-624b0bcbb2f4 \
  -H "Authorization: Bearer fondaro_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"status": "sold"}'
```

```json
{
  "id": "29a1e184-237a-40c8-a1fe-624b0bcbb2f4",
  "referenceNumber": "FDR-7KQ2MX9A",
  "status": "sold"
}
```

An ordinary edit never changes the status, and a payload with no real change writes nothing (neither `updatedAt` nor history moves).

## Renew a listing

### `PUT /properties/:id/renew`

Sets `expiresAt` to two months from now, stamps `lastRenewedAt` and makes an `inactive` listing `active` again. Other statuses are kept. Needs `properties:write`.

```bash
curl -X PUT https://api.fondaro.com/properties/29a1e184-237a-40c8-a1fe-624b0bcbb2f4/renew \
  -H "Authorization: Bearer fondaro_pk_abc123"
```

```json
{
  "id": "29a1e184-237a-40c8-a1fe-624b0bcbb2f4",
  "status": "active",
  "expiresAt": "2026-12-02T10:00:00.000Z",
  "lastRenewedAt": "2026-10-02T10:00:00.000Z"
}
```

**Automatic renewal.** With `autoRenewEnabled: true` on the listing, the daily expiry check renews an `active` listing at `expiresAt` instead of making it `inactive`, and sends no expiry emails for it. A listing that is not active is not renewed automatically.

## List expiring listings

### `GET /properties/expiring/soon`

Your listings that expire within a window, including those set to renew automatically. Needs `properties:read`.

| Query parameter | Type | Meaning |
|---|---|---|
| `days` | integer | Window in days (default 30) |
| `agentUserIds` | string[] | Only listings assigned to these people, by user id; repeat the key, up to 50 |

```bash
curl "https://api.fondaro.com/properties/expiring/soon?days=14" \
  -H "Authorization: Bearer fondaro_pk_abc123"
```

```json
[
  {
    "id": "29a1e184-237a-40c8-a1fe-624b0bcbb2f4",
    "referenceNumber": "FDR-7KQ2MX9A",
    "status": "active",
    "expiresAt": "2026-10-12T10:00:00.000Z",
    "autoRenewEnabled": false
  }
]
```

## Imported listings

A listing brought in from another system carries where it came from:

| Field | Meaning |
|---|---|
| `externalSource` | The source system, for example `resales_online` |
| `externalRef` | The listing's stable id there, used to update rather than duplicate |
| `lastSyncedAt` | The last time imported fields were written |

They are `null` on listings you created. A re-import updates the imported fields but never the assigned agent, your commission, the lead group, or a status you changed. A listing missing from a later import is not deactivated. See [Resales import](https://www.fondaro.com/docs/api/resales-own-listings-import.md).

## History

Every change writes a history event; clients never write them. Read them with `GET /properties/:id/activity?types=change` (see [Activity and viewings](https://www.fondaro.com/docs/api/properties/activity.md#read-activity)).

| Field | Meaning |
|---|---|
| `type` | `created`, `updated`, `status_changed`, `renewed`, `imported`, `deleted` |
| `changes` | `[{ field, from, to }]`; images and translations may be summarised |
| `source` | `user`, `admin`, `import` or `system` (automatic renewal and expiry) |
| `actorUserId` | Who made it, when a person did |

```json
{
  "id": "307e83ce-6cb1-40da-87e4-81a76399f858",
  "propertyListingId": "29a1e184-237a-40c8-a1fe-624b0bcbb2f4",
  "actorUserId": "user_2abc123",
  "type": "status_changed",
  "changes": [{ "field": "status", "from": "active", "to": "sold" }],
  "source": "user",
  "createdAt": "2026-10-02T15:40:00.000Z"
}
```

## Errors

| Status | When |
|---|---|
| `400` | `status` is not `sold`, `rented` or `deleted`, or `agentUserIds` has more than 50 ids |
| `404` | The listing does not exist or is not yours |

Source: https://www.fondaro.com/docs/api/properties/own-listings