Notifications

Cypress already notifies your members: an offer arrived, a task fell due, a closing step is late. The API gives your systems the same notifications, each with its recipient, so an app can route them where your team works and an agent can hear what it was told. Nothing new is added to what Cypress sends: these are the notifications your members already get. Since 1.5.0.

Neither is a default scope. Both an API key and a Connect Cypress token are accepted.

A notification is an event with a recipient

Every notification Cypress sends to one of your members is also a NOTIFICATION.CREATED event in your organization's event log, with the notification as its body:

{
  "id": "ntf_6c1e…",
  "type": "OFFER_DECLINED",
  "title": "Offer declined",
  "message": "Your offer on the 2022 Toyota RAV4 was declined.",
  "severity": "INFO",
  "actionUrl": "https://app.getcypress.ai/offers?v=clx…",
  "vehicleId": "clx…",
  "recipient": { "userId": "clx…", "kind": "PERSON", "name": "Ana Ruiz" },
  "createdAt": "2026-10-15T14:02:11.000Z"
}

• It is yours when your member is the recipient. A notification to your buyer about another company's car is in your log, and that company never hears of it. A notification about your car sent to someone else's member is in theirs, not yours.
• Agents hear only this way. Cypress never emails an agent or puts anything in its inbox: a notification addressed to an agent is this event and nothing else (recipient.kind is AGENT).
• Once each. A notification that goes out inside a bundled email is still its own event, and a retry is the same event.
• type is a label, not a closed list. New kinds of notification appear as Cypress adds them; route on type where you know it and fall back on title and message.
• A buy plan match names its target. Since 1.9.0 a BUY_PLAN_MATCH notification carries targetId (the buy target) beside vehicleId (the car that matches it); other notifications have no targetId.

Subscribe

NOTIFICATION.CREATED is opt-in, like TASK.*: only a Cypress-dialect subscription that lists it gets it, and the key that subscribes needs notifications:read. To follow chosen people instead of the whole organization, list their user ids in entityIds (GET /api/v1/members lists your people and agents):

curl -X POST "$BASE/api/v1/webhooks/subscriptions" \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{
    "callback": "https://ops.example.com/cypress",
    "eventTypes": ["NOTIFICATION.CREATED"],
    "entityIds": ["usr_ana…", "usr_scout…"]
  }'

The envelope's resource is notifications, its href is /api/v1/notifications/{id}, and the vehicle a notification is about, if any, rides in relatedResources.

Read them back

curl "$BASE/api/v1/notifications?limit=50" -H "authorization: Bearer $TOKEN"
curl "$BASE/api/v1/notifications?userId=clx…" -H "authorization: Bearer $TOKEN"
curl "$BASE/api/v1/notifications?recipient=me" -H "authorization: Bearer $AGENT_TOKEN"

The last 30 days, newest first. recipient=me is the person or agent a token acts as (an API key is nobody: 422). Page back with before=<nextCursor> while hasMore is true. Each item carries its cursor in your event log, so GET /api/v1/events?after=… picks up from the same place.

Preferences

Each person chooses which notifications reach them by email and in the app's inbox. The API reads and sets the same choices:

curl "$BASE/api/v1/notifications/preferences?userId=clx…" -H "authorization: Bearer $TOKEN"

curl -X PATCH "$BASE/api/v1/notifications/preferences" \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{ "userId": "clx…", "workflow": "offer.received", "channels": { "email": false } }'

• Whose. An app a person connected reads and sets that person's preferences only (leave userId out). An API key is your organization's: it names any active person with userId. An agent has no preferences (it hears notifications as events) and sets no one's: 403 PEOPLE_ONLY.
• What. The read lists the notifications a person may switch off, each with its workflow name and its email and inApp channels. A notification Cypress marks as one that cannot be switched off is not listed, and asking to change one, or a name that is not on the list, is 422.
• Recorded. Every change goes in your organization's audit log with the key or app that made it.