> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withclasp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

Notifications represent important business events that should typically result in communications to a member, broker, or employer. For example, a new hire becoming eligible for benefits or a member submitting an enrollment will both create Notification objects in Clasp. The Notifications API lets you stay in the loop so that you are able to control communications via your own channels and templates instead of having Clasp send them.

## Overview

When an important business event occurs, such as a new hire becoming eligible for benefits, Clasp creates a notification object. If the notification is "Clasp managed", Clasp will immediately send an email. Otherwise, Clasp will only emit a webhook informing you of the new Notification and will not send an email. Please reach out to Clasp to configure which notification types are Clasp managed vs Partner managed.

## Notification Object

Each notification has the following structure:

```json theme={null}
{
  "id": "noti_8Ln4MbSf5uLFurmAOfNr9",
  "notification_type": "welcome",
  "related_object_type": "member",
  "related_object_id": "mem_kBRoHxraaHbXO9K4JXIRP",
  "payload": {
    "first_name": "John",
    "employer_name": "ABC Company"
  },
  "owner": "partner",
  "created_at": "2025-01-06T05:41:19.093833Z"
}
```

### Field Descriptions

* `id`: Unique identifier for the notification
* `notification_type`: Which type of notification this is. For example, `welcome` is created for new hires and `enrollment_submitted` after a member submits their enrollment
* `related_object_type`: The type of object this notification is about (e.g. `member`, `enrollment`, `open_enrollment_window`)
* `related_object_id`: ID of the object this notification is about
* `payload`: Commonly used information for notifications of this type that can be populated into your communications
* `owner`: Who is responsible for delivering this notification (`partner` or `clasp`)
* `created_at`: Timestamp when the notification was created

### Notification Types

| Notification Type          | Created When                                         | Related Object Type      |
| -------------------------- | ---------------------------------------------------- | ------------------------ |
| `welcome`                  | A new hire should be welcomed and invited to enroll  | `member`                 |
| `newly_eligible`           | A member becomes eligible for benefits               | `member`                 |
| `member_terminated`        | A member is terminated                               | `member`                 |
| `dependent_age_out`        | A member's dependent is about to age out of coverage | `member`                 |
| `enrollment_submitted`     | A member submits their enrollment                    | `enrollment`             |
| `enrollment_approved`      | A member's enrollment is approved                    | `enrollment`             |
| `open_enrollment_kickoff`  | An open enrollment window opens                      | `open_enrollment_window` |
| `open_enrollment_reminder` | A member has not yet completed open enrollment       | `open_enrollment_window` |

New notification types will be added over time.

## Receiving Notifications via Webhooks

Notifications work together with [webhooks](/guides/webhooks). When a notification is created, Clasp sends a webhook event with `object_type` set to `notification` and the notification's ID:

```json theme={null}
{
  "id": "evnt_8Ln4MbSf5uLFurmAOfNr9",
  "event_type": "created",
  "object_id": "noti_8Ln4MbSf5uLFurmAOfNr9",
  "object_type": "notification",
  "employer": "er_67Al5UIOFMPsrHbLI8YnU",
  "created_at": "2025-01-06T05:41:19.093833Z"
}
```

When you receive this event:

1. Fetch the notification content with `GET /notifications/{object_id}`
2. Check the `owner` field. If the owner is `clasp`, Clasp will have initiated an email already.
3. Leverage the `notification_type`, `related_object_type`, and `related_object_id` to identify what type of communications are required and for whom.
4. Use the `payload` for notification specific data that is snapshotted at the time of the notification being created.

See the [Webhooks guide](/guides/webhooks) for details on configuring your endpoint and verifying event signatures.