# Create Notification Channel

#### Description
Creates a new channel for receiving notifications when changes occur.

Notification channels can be created with additional filters which can be thought of as a subset of those available when [reading events](/developers/api/events/read-events/index.md).

Each Account connected to your Application has a limit of **128** channels, though we recommend only using one.

#### URL format
```
{data_center_url}/v1/channels
```

#### Example Request
```http
POST /v1/channels HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "callback_url": {CALLBACK_URL},
  "filters": {
    "calendar_ids": ["cal_n23kjnwrw2_sakdnawerd3"],
    "only_managed": false
  }
}
```

#### Example Response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "channel": {
    "channel_id": "chn_54cf7c7cb4ad4c1027000001",
    "callback_url": {CALLBACK_URL},
    "filters": {
      "calendar_ids": ["cal_n23kjnwrw2_sakdnawerd3"],
      "only_managed": false
    }
  }
}
```

#### Request parameters
##### `data_center_url` *(required)*

The URL for the data center you want to communicate with. Possible choices are:

- `api-au.cronofy.com` - Australia
- `api-ca.cronofy.com` - Canada
- `api-de.cronofy.com` - Germany
- `api-sg.cronofy.com` - Singapore
- `api-uk.cronofy.com` - United Kingdom
- `api.cronofy.com` - United States

Find out more about [Cronofy's data centers](/developers/data-centers/index.md).
##### `callback_url` *(required)*

The HTTP or HTTPS URL you wish to receive [push notifications](/developers/api/push-notifications/index.md). HTTPS is strongly preferred.

##### `filters.calendar_ids` *(optional)*

Restricts the notifications to changes to events within the specified calendars.

The possible `calendar_id`s can be discovered through the [list calendars endpoint](/developers/api/calendars/list-calendars/index.md).

If omitted, notifications are sent for changes to events across all calendars. When specified, at least one `calendar_id` must be provided.

##### `filters.only_managed` *(optional)*

A [`Boolean`](/developers/api/data-types/index.md) specifying whether only events that you are managing for the account should trigger notifications.

By default all events trigger notifications, both those created by the user and those you are managing.

#### Response parameters
##### `channel.channel_id`

The ID of the channel.

Note that ID may be for an existing channel if you make a request to create a channel that is identical to an existing one.

##### `channel.callback_url`

The URL that will receive push notification requests.

##### `channel.filters`

Any non-default filters that were specified for the channel.

#### Error responses
##### 401 Unauthorized

The request was refused as the provided [authentication credentials](/developers/api/authentication/index.md) were not recognized.

When an OAuth `refresh_token` is available then it should be used to [request a replacement `auth_token`](/developers/api/authorization/refresh-token/index.md) before the request is retried.

##### 422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required `callback_url` parameter, you would receive a response like:

```json
{
  "errors": {
    "callback_url": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}
```

The `key` field is intended for programmatic use and the `description` field is a human-readable equivalent.



---
[Read in HTML](/developers/api/push-notifications/create-channel/)