AthausDocs

REST API: events

What happened in the office, available for 30 days. The same events that go to webhooks, filtered by type and time.

Last updated:

GET /v1/events returns what happened in the office: new inquiries and messages, booked, canceled and upcoming viewings, files that were read. These are the same events a webhook receives, with the same id. Use the list when you have no address, missed a webhook, or want to catch up after an outage.

curl "https://api.athaus.ai/v1/events?type=inquiry.received&limit=2" \
  -H "Authorization: Bearer ath_live_..."
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44",
      "type": "inquiry.received",
      "createdAt": "2026-11-12T08:14:03.512Z",
      "apiVersion": "v1",
      "livemode": true,
      "data": {
        "object": {
          "object": "inquiry",
          "id": "0190f3c1-2217-7a02-8c4b-5e1d7a9b3f10",
          "listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
          "status": "new",
          "source": "athaus",
          "answered": false,
          "replyable": true,
          "name": "Mia K.",
          "email": null,
          "phone": null,
          "contactId": null,
          "contactConsent": "not_requested",
          "seeker": null,
          "createdAt": "2026-11-12T08:14:03Z",
          "updatedAt": "2026-11-12T08:14:03Z"
        }
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJzIjoiLWNyZWF0ZWRBdCIsLi4ufQ"
}

What an event is

{ object: "event", id, type, createdAt, apiVersion, livemode, data: { object } }.

  • type is one of the names in the webhook table. New types arrive without a new version: ignore what you do not know.
  • data.object is the resource the event is about, in the shape /v1 reads it. It is in the state of now, not in the state of the event: if you need the state of back then, you have to keep it when it is delivered. If the resource no longer exists, you get { "object": "viewing", "id": "...", "deleted": true } instead.
  • What a GET does not return is not here either. Name, email and phone of a seeker appear only while they have released them to the office.
  • apiVersion is the version the data is shaped in.
  • livemode is false for an event of the test office.

How long, and who sees what

An event is available for 30 days; after that GET /v1/events/{id} answers 404 and the list no longer shows it.

A key sees only the events of the resources it may read: without read on viewings it misses the three viewing types. It sees proposal.pending only for proposals it created itself. Asking for a type outside that is 403 (insufficient_permissions). A single event outside it is 404. The list needs the scope read, but no level on a resource of its own.

Filter and page

ParameterEffect
typeonly events of this type
createdSinceonly events from this instant on (ISO 8601, inclusive)
createdBeforeonly events before this instant
limit, cursoras everywhere, see Pagination

The list is sorted by createdAt descending, newest first, and the order is fixed. There is no sort and no updatedSince: an event never changes.

Catch up after an outage

Keep the id of the newest event you processed and the time of its createdAt. Read with createdSince from that time, page to the end and skip what you already have. Events with the same time arrive exactly once, also across page boundaries.

curl "https://api.athaus.ai/v1/events/0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44" \
  -H "Authorization: Bearer ath_live_..."

Both operations are in the reference.

Keep reading

On this page