# Filtering and delta sync

The single most useful parameter on this API is `updated_after`. Combined with
cursor pagination it turns "re-read the whole portfolio" into "fetch what
changed", which is what keeps you inside your rate limit as a workspace grows.

## Common filters

Available on every list endpoint:

| Parameter | Behaviour |
| --- | --- |
| `ids` | Comma-separated ids. Up to 200 |
| `created_after` / `created_before` | Filter on creation time (RFC 3339) |
| `updated_after` / `updated_before` | Filter on last modification. The delta-sync workhorse |
| `limit` / `cursor` | [Pagination](/pagination) |

Reservations additionally support `property_id`, `status`, `channel`,
`checkin_from` / `checkin_to` and `checkout_from` / `checkout_to`.

## The delta-sync loop

1. Do one full read to seed your copy. Record the **latest `updated_at`** you
   saw — call it your watermark.
2. On each subsequent run, request `updated_after=<watermark>` and page until
   `has_more` is `false`.
3. Advance the watermark to the newest `updated_at` in the results.

```bash
curl "https://api.wearenoe.fr/v1/reservations?updated_after=2026-08-18T09:30:00Z&limit=200" \
  -H "Authorization: Bearer $NOE_API_KEY"
```

Records are returned most-recently-modified first, so the newest `updated_at` is
in the first item of the first page.

### Overlap your watermark slightly

Rewind it by a minute or so rather than using the exact last value. Records
modified in the same instant your previous run finished can otherwise fall in
the gap. Every record carries a stable `id`, so re-reading a handful is a
harmless upsert — missing one is not.

## Use `expand` instead of a second request

Rather than fetching a reservation and then its property, ask for both at once:

```bash
curl "https://api.wearenoe.fr/v1/reservations?expand=property,guest" \
  -H "Authorization: Bearer $NOE_API_KEY"
```

`expand=guest` requires the `reservations:guest_read` scope. Without it the
field is omitted and the request still succeeds — see [Scopes](/scopes).

## Webhooks are the optimisation, polling is the guarantee

[Webhooks](/webhooks) will tell you about most changes within seconds and will
remove the bulk of your polling. They are not a replacement for delta sync:
delivery is at-least-once and an endpoint that is down long enough will exhaust
its retries.

Run a periodic `updated_after` reconciliation as well — hourly is plenty for
most integrations. That combination gives you low latency from webhooks and
correctness from polling, and it is what we recommend to every integration.