---
title: "How do I subscribe to an event?"
slug: "how-do-i-subscribe-to-an-event"
updated: 2025-04-16T14:07:53Z
published: 2025-04-16T14:07:53Z
canonical: "support.lusid.com/how-do-i-subscribe-to-an-event"
---

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

# How do I subscribe to an event?

Providing you are a LUSID user with sufficient privileges, you can create a subscription to a particular event, for example the LUSID ‘portfolio created’ event. [See the list of events](/v1/docs/what-system-events-can-i-subscribe-to).

You can then attach [email](/v1/docs/how-do-i-notify-people-via-email-when-an-event-occurs), [SMS](/v1/docs/how-do-i-notify-people-via-sms-when-an-event-occurs), [webhook](/v1/docs/how-do-i-create-a-webhook-to-call-a-lusid-api-when-an-event-occurs) and/or [AWS SQS](/v1/docs/how-do-i-send-an-amazon-simple-queue-service-sqs-notification-when-an-event-occurs) notifications to the subscription in order to inform people and/or take action when the event occurs.

**Note:** For creating and updating tasks in the Workflow Service when LUSID emits a system event, see [system event handlers](/v1/docs/how-do-i-use-system-event-handlers-to-automatically-create-or-update-tasks) instead.

## Using the LUSID web app

1. Sign in to the [LUSID web app](https://www.lusid.com/app) as a user with suitable permissions.
2. From the top left menu, select **Notifications Management > Subscriptions**.
3. Click the **Create subscription** button and follow the instructions: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(738).png)

## Using the Notification REST API

Currently, you can create one subscription per API call.

1. [Obtain an API access token](/v1/docs/how-do-i-obtain-and-use-a-short-lived-api-access-token-from-okta).
2. Call the [CreateSubscription](https://www.lusid.com/docs/api/notification/endpoints/subscriptions/CreateSubscription/) API for your LUSID domain, passing in your API access token and:

The following example subscribes to the `PortfolioCreated` event conditionally; that is, when a portfolio is created in the `Finbourne-Examples` scope:

```json
curl -X POST "https://<your-domain>.lusid.com/notification/api/subscriptions" 
  -H "Authorization: Bearer <your-API-access-token>" 
  -H "Content-Type: application/json" 
  -d '{
  "id": {
    "scope": "PortfolioEvents",
    "code": "PortfolioCreatedEvent"
  },
  "displayName": "PortfolioCreatedInExampleScope",
  "description": "Subscribe to the event fired when a portfolio is created in the Finbourne-Examples scope",
  "status": "Active",
  "matchingPattern": {
    "eventType": "PortfolioCreated",
    "filter": "Body.portfolioScope eq 'Finbourne-Examples'"
  },
  "useAsAuth": "00uji4ve5haBc1Hlf2p7"  
}'
```

The response is as follows:

```json
{
  "id": {
    "scope": "PortfolioEvents",
    "code": "PortfolioCreatedEvent"
  },
  "displayName": "PortfolioCreatedInExampleScope",
  "description": "Subscribe to the event fired when a portfolio is created in the Finbourne-Examples scope",
  "status": "Active",
  "matchingPattern": {
    "eventType": "PortfolioCreated",
    "filter": "Body.portfolioScope eq 'Finbourne-Examples'"
  },
  "createdAt": "2022-07-08T10:13:36.8915431+00:00",
  "userIdCreated": "00u91lo2d7X42sdse2p7",
  "modifiedAt": "2022-07-08T10:13:36.8915431+00:00",
  "userIdModified": "00u91lo2d7X42sdse2p7",
  "useAsAuth": "00uji4ve5haBc1Hlf2p7",
  "href": "https://<your-domain>.lusid.com/notification/api/subscriptions/PortfolioEvents/PortfolioCreatedEvent"
}
```
  - A `scope` and `code` that together uniquely identify the subscription.
  - An `eventType` that is the `id` of the event you want to subscribe to. [See how to find this out](/v1/docs/what-system-events-can-i-subscribe-to).
  - Optionally, a `filter` to subscribe to the event [conditionally](/v1/docs/using-lusid-filtering-syntax-to-subscribe-to-events-conditionally).
  - Optionally, a service user ID for `useAsAuth`. If omitted, the subscription is created on behalf of the user sending the request. This means if the Personal user account is deleted, any subscriptions created on the user's behalf will be affected. We recommend users instead create subscriptions on behalf of service users with `useAsAuth`; [read more on it here](/v1/docs/setting-up-a-schedule-subscription-or-other-activity-on-behalf-of-a-service-user).

Once subscribed, you should attach at least one [email](/v1/docs/how-do-i-notify-people-via-email-when-an-event-occurs), [SMS](/v1/docs/how-do-i-notify-people-via-sms-when-an-event-occurs), [webhook](/v1/docs/how-do-i-create-a-webhook-to-call-a-lusid-api-when-an-event-occurs) or [AWS SQS](/v1/docs/how-do-i-send-an-amazon-simple-queue-service-sqs-notification-when-an-event-occurs) notification to the subscription in order to actually notify someone or perform an operation.