--- title: "Subscribe or unsubscribe channels to/from subscription lists" method: POST path: "/api/channels/subscription_lists" tags: ["Channels"] --- # Subscribe or unsubscribe channels to/from subscription lists `POST /api/channels/subscription_lists` ## Request - Base URL: `https://go.urbanairship.com` - URL: `https://go.urbanairship.com/api/channels/subscription_lists` - Auth: one of: - HTTP basic - HTTP basic - HTTP bearer - OAuth 2 - Client credentials - Token URL: `http://oauth2.{domain}.com/token` scopes: `chn` - TypeScript: (a function with typed inputs; its response is checked against the schema) Subscribe or unsubscribe channels to/from subscription lists. ## Request body - union - object: The request payload must be a JSON object with the following fields. - `AND` union[] - union - union: Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. - object: AND selector - `AND` union[] - … - object: OR selector - `OR` union[] - … - object: NOT selector - `NOT` union - … - union: Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a channel ID or metadata that maps to the device (or multiple devices) such as a tag. - object: A tag is an arbitrary bit of metadata used for targeting devices. A tag specifier may or may not have an associated group declaration, indicating a `tag group` the tag belongs to, for example, `{"tag": "silver-member", "group": "loyalty"}`. If no tag group is specified, the default `device` group is used. - `group` string - `tag` union, required - … - object: The segment ID. - `segment` union, required - … - object: The unique channel identifier used to target an open channel device or web device, i.e., web browser. - `channel` union, required - … - object: A `named_user` is an alternate, non-unique name, mapped to a user profile in a different database, e.g., CRM, that can be used to target devices associated with that profile. - `named_user` union, required - … - object: The unique channel identifier used to target a Fire OS device. - `amazon_channel` union, required - … - object: The unique channel identifier used to target an Android device. - `android_channel` union, required - … - object: The unique channel identifier used to target a device on an open platform. - `open_channel` union, required - … - object: Selects a single SMS device. The `msisdn` must be `opted_in` to receive notifications. - `msisdn` string, required: The recipient phone number. - `sender` string, required: The sender that the app is configured to send SMS messages from. - object: A `static_list` is a subset of your audience defined by a CSV file containing channel IDs or named users. - `static_list` union, required - … - object: An single instance or array of subscription list IDs. - `subscription_list` union, required - … - object: An attribute object with a `TEXT` schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or named user. - `attribute` string, required: The key for the text attribute that you previously defined in the Airship UI, e.g., `"item_purchased"`. - `operator` 'equals' | 'contains' | 'less' | 'greater' | 'is_empty', required: The operator used to evaluate the attribute expression. - `value` string, required: The string you want to match when evaluating the attribute expression, e.g., `"jeans"`. - object: An attribute object with a `NUMBER` schema type. Performs value comparisons based on the number value for an attribute on a channel or named user. - `attribute` string, required: The key for the number attribute that you previously defined in the Airship UI, e.g., `"lifetime_value"`. - `operator` 'equals' | 'contains' | 'less' | 'greater' | 'is_empty', required: The operator used to evaluate the attribute expression. - `value` number, required: The value of the number attribute that you are targeting. For example, `15000`. - object: An attribute object with a `DATE` schema type. Performs absolute date comparisons for ISO-formatted date values or a relative date comparisons given an integer `value` and `precision`, e.g., `days`, `months`. Use a date attribute to target a channel or named user based on the date values. - `attribute` string, required: The key for the date attribute that you previously defined in the Airship UI, e.g., `"birth_date"`. - `operator` 'is_empty' | 'before' | 'after' | 'range' | 'equals', required: The operator used to evaluate the attribute expression. The `operator` that you use with a date attribute will determine which additional properties will be required in the object. See table for required fields. | Operator | Required properties | |---|---| | `is_empty` | `attribute` | | `before` | `attribute`, `value`, `precision`\* | | `after` | `attribute`, `value`, `precision`\* | | `range` | `attribute`, `value` | | `equals` | `attribute`, `value`, `precision`\*\* | \* *`precision` is required, but enum values are different than with an equals operator* \*\* *`precision` is required, but enum values are different than with a before or after operator* **Date Attribute Operators**: * `is_empty`— Evaluates to true if a channel or named user does not have a value for the attribute. * `before`— Value is one of: - *String*, ISO 8601 inclusive date, optionally including an offset, e.g., `2007-03-01T13:00:00+08:00`. The value will be converted and stored as UTC. - *Integer*, Relative number of units from the current time (i.e., now) into the past. Example: `"before": 20` indicates "at least 20 years ago" given a `precision` of `years`. - *String* with the value `"now"`, representing the current date-time, i.e., "before now". When using the `now` value, no `precision` is required. **Note**: When using the `before` operator, precision value must be one of `years`, `months`, `days`, `hours`, or `minutes`. * `after`— Values for `after` behave identically to `before`, as described above. * `range`— An ISO 8601 time interval. The format consists of an inclusive start and an exclusive end time date separated with a `/`, e.g., `2019-03-01T13:00:00/2019-05-11T15:30:00`. `range` does not have a precision. * `equals`— allows for selecting specific or non-specific dates as determined by the `precision` provided in the attribute object. **Note**: When using the `equals` operator, `precision` must be one of: - `day` — an integer which represents the day of the month or "now". - `month` — an integer which represents the month of the year starting with 1 for Jan or "now" which will use the value of the current month. - `month_day` — a string in the format of "mm-dd" which represents a month and day. Ex. 05-04 is May 4th. Value can also be "now". If today is 2020-03-09, then value will be "03-09". - `year_month` — a string in the format of "yyyy-mm" which represents a year and month. Ex. 2020-05 is May 2020. Value can also be "now". If today is 2020-03-09, then value will be "2020-03". - `year_month_day` — a string in the format of "yyyy-mm-dd" which represents a specific year, month, and day. Ex. 2020-05-04. Value can also be "now". If today is 2020-03-09, then value will be "2020-03-09". - or value can be "now" which is the current date-time. - `precision` 'years' | 'months' | 'days' | 'hours' | 'minutes' | 'day' | 'month' | 'month_day' | 'year_month' | 'year_month_day': The precision, expressed as a timing interval unit, that Airship uses to evaluate a date attribute expression. - `relative_to` 'future' | 'past': Specifies whether the date is in the `future` or in the `past`. If missing, it defaults to `past`. - `value` union - … - object: An attribute object with a `JSON` schema type. Performs value comparisons based on the JSON value for an attribute on a channel or named user. - `attribute` string, required: The name of the attribute. - `where` object, required: An object that filters on the JsonPath expression that you provide. - … - object: The `activity` object defines the target audience based on lifecycle actions or custom event activity, using comparison operators on activity count and recency. Optionally include a `where` object, which filters for specific activity values. In the example to the right, the target audience is users who have opened your app from a notification from the "neowise" campaign at least twice, 3 days ago. - `activity` 'app_open' | 'message_received' | 'message_center_read' | 'message_center_delivered' | 'message_center_deleted' | 'in_app_message_display' | 'in_app_message_resolution' | 'in_app_message_expiration' | 'screen_view' | 'web_session' | 'web_click' | 'short_link_click' | 'first_seen' | 'sms_aborted' | 'sms_delivered' | 'sms_dispatched' | 'sms_expired' | 'sms_failed' | 'sms_rejected' | 'sms_undeliverable' | 'sms_unknown' | 'email_bounce' | 'email_click' | 'email_delay' | 'email_delivered' | 'email_injection' | 'email_open' | 'email_unsubscribe' | 'scene_displayed' | 'scene_completed' | 'scene_incomplete' | 'survey_displayed' | 'survey_submitted' | 'survey_not_submitted', required: The target event activity, e.g., `app_open`. Default event values are enumerated below. If you create a custom or predefined event that you wish to segment users on, you must register the event in the Airship dashboard. See [Adding events to your project](/guides/audience/events/adding/). - `after` union: A date value for an absolute comparison or an integer value for a relative comparison. - … - `before` union: A date value for an absolute comparison or an integer value for a relative comparison. - … - `metric` 'count' | 'total_value' | 'last' | 'first': The metric you are targeting for the event. When using the metric `count` or `total_value`, `operator` and `value` are required. When using either `first` or `last`, `operator` and `value` are not allowed. Use one of the following combinations instead: * `before`/`precision` * `after`/`precision` * `on`/`on_precision` | Metric | Description | |---|---| | `count` | Evaluate based on the number of event occurrences. | | `total_value` | Evaluate based on the cumulative event `value` associated with the target user. | | `last` | Evaluate based on the last occurrence of an event for a given user/time window. | | `first` | Evaluate based on the first occurrence of an event for a given user/time window. | - `on` string, date-time: A [date-time](/developer/rest-api/ua/introduction/#date-time-format). - `on_precision` 'day' | 'month' | 'month_day' | 'year_month' | 'year_month_day': When using the `first` or `last` metric with the `on` property to target events on. For example, for the 5th of any month, or only in March, use `on_precision`. - `operator` 'greater' | 'less' | 'equals' | 'greater_eq' | 'less_eq', required: The comparison operator used to evaluate the activity expression. Use these operators (greater/less than, equal to, equal or greater/equal or less) when the `metric` is either `count` or `total_value`. - `precision` 'days' | 'weeks' | 'months' | 'years': If using a relative number (integer) for the `before`/`after`/`on` property, the `precision` value will be interpreted as the number of time units ago, e.g., *7 days ago*. Defaults to `days`. - `value` number, required: The value that the `operator` uses to evaluate the target audience. - `where` WhereObject: `where` is an object that filters on the existence of prior user activity, specified by event properties that you provide. - … - object: The request payload must be a JSON object with the following fields. - `OR` union[] - union - union: Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. - object: AND selector - `AND` union[] - … - object: OR selector - `OR` union[] - … - object: NOT selector - `NOT` union - … - union: Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a channel ID or metadata that maps to the device (or multiple devices) such as a tag. - object: A tag is an arbitrary bit of metadata used for targeting devices. A tag specifier may or may not have an associated group declaration, indicating a `tag group` the tag belongs to, for example, `{"tag": "silver-member", "group": "loyalty"}`. If no tag group is specified, the default `device` group is used. - `group` string - `tag` union, required - … - object: The segment ID. - `segment` union, required - … - object: The unique channel identifier used to target an open channel device or web device, i.e., web browser. - `channel` union, required - … - object: A `named_user` is an alternate, non-unique name, mapped to a user profile in a different database, e.g., CRM, that can be used to target devices associated with that profile. - `named_user` union, required - … - object: The unique channel identifier used to target a Fire OS device. - `amazon_channel` union, required - … - object: The unique channel identifier used to target an Android device. - `android_channel` union, required - … - object: The unique channel identifier used to target a device on an open platform. - `open_channel` union, required - … - object: Selects a single SMS device. The `msisdn` must be `opted_in` to receive notifications. - `msisdn` string, required: The recipient phone number. - `sender` string, required: The sender that the app is configured to send SMS messages from. - object: A `static_list` is a subset of your audience defined by a CSV file containing channel IDs or named users. - `static_list` union, required - … - object: An single instance or array of subscription list IDs. - `subscription_list` union, required - … - object: An attribute object with a `TEXT` schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or named user. - `attribute` string, required: The key for the text attribute that you previously defined in the Airship UI, e.g., `"item_purchased"`. - `operator` 'equals' | 'contains' | 'less' | 'greater' | 'is_empty', required: The operator used to evaluate the attribute expression. - `value` string, required: The string you want to match when evaluating the attribute expression, e.g., `"jeans"`. - object: An attribute object with a `NUMBER` schema type. Performs value comparisons based on the number value for an attribute on a channel or named user. - `attribute` string, required: The key for the number attribute that you previously defined in the Airship UI, e.g., `"lifetime_value"`. - `operator` 'equals' | 'contains' | 'less' | 'greater' | 'is_empty', required: The operator used to evaluate the attribute expression. - `value` number, required: The value of the number attribute that you are targeting. For example, `15000`. - object: An attribute object with a `DATE` schema type. Performs absolute date comparisons for ISO-formatted date values or a relative date comparisons given an integer `value` and `precision`, e.g., `days`, `months`. Use a date attribute to target a channel or named user based on the date values. - `attribute` string, required: The key for the date attribute that you previously defined in the Airship UI, e.g., `"birth_date"`. - `operator` 'is_empty' | 'before' | 'after' | 'range' | 'equals', required: The operator used to evaluate the attribute expression. The `operator` that you use with a date attribute will determine which additional properties will be required in the object. See table for required fields. | Operator | Required properties | |---|---| | `is_empty` | `attribute` | | `before` | `attribute`, `value`, `precision`\* | | `after` | `attribute`, `value`, `precision`\* | | `range` | `attribute`, `value` | | `equals` | `attribute`, `value`, `precision`\*\* | \* *`precision` is required, but enum values are different than with an equals operator* \*\* *`precision` is required, but enum values are different than with a before or after operator* **Date Attribute Operators**: * `is_empty`— Evaluates to true if a channel or named user does not have a value for the attribute. * `before`— Value is one of: - *String*, ISO 8601 inclusive date, optionally including an offset, e.g., `2007-03-01T13:00:00+08:00`. The value will be converted and stored as UTC. - *Integer*, Relative number of units from the current time (i.e., now) into the past. Example: `"before": 20` indicates "at least 20 years ago" given a `precision` of `years`. - *String* with the value `"now"`, representing the current date-time, i.e., "before now". When using the `now` value, no `precision` is required. **Note**: When using the `before` operator, precision value must be one of `years`, `months`, `days`, `hours`, or `minutes`. * `after`— Values for `after` behave identically to `before`, as described above. * `range`— An ISO 8601 time interval. The format consists of an inclusive start and an exclusive end time date separated with a `/`, e.g., `2019-03-01T13:00:00/2019-05-11T15:30:00`. `range` does not have a precision. * `equals`— allows for selecting specific or non-specific dates as determined by the `precision` provided in the attribute object. **Note**: When using the `equals` operator, `precision` must be one of: - `day` — an integer which represents the day of the month or "now". - `month` — an integer which represents the month of the year starting with 1 for Jan or "now" which will use the value of the current month. - `month_day` — a string in the format of "mm-dd" which represents a month and day. Ex. 05-04 is May 4th. Value can also be "now". If today is 2020-03-09, then value will be "03-09". - `year_month` — a string in the format of "yyyy-mm" which represents a year and month. Ex. 2020-05 is May 2020. Value can also be "now". If today is 2020-03-09, then value will be "2020-03". - `year_month_day` — a string in the format of "yyyy-mm-dd" which represents a specific year, month, and day. Ex. 2020-05-04. Value can also be "now". If today is 2020-03-09, then value will be "2020-03-09". - or value can be "now" which is the current date-time. - `precision` 'years' | 'months' | 'days' | 'hours' | 'minutes' | 'day' | 'month' | 'month_day' | 'year_month' | 'year_month_day': The precision, expressed as a timing interval unit, that Airship uses to evaluate a date attribute expression. - `relative_to` 'future' | 'past': Specifies whether the date is in the `future` or in the `past`. If missing, it defaults to `past`. - `value` union - … - object: An attribute object with a `JSON` schema type. Performs value comparisons based on the JSON value for an attribute on a channel or named user. - `attribute` string, required: The name of the attribute. - `where` object, required: An object that filters on the JsonPath expression that you provide. - … - object: The `activity` object defines the target audience based on lifecycle actions or custom event activity, using comparison operators on activity count and recency. Optionally include a `where` object, which filters for specific activity values. In the example to the right, the target audience is users who have opened your app from a notification from the "neowise" campaign at least twice, 3 days ago. - `activity` 'app_open' | 'message_received' | 'message_center_read' | 'message_center_delivered' | 'message_center_deleted' | 'in_app_message_display' | 'in_app_message_resolution' | 'in_app_message_expiration' | 'screen_view' | 'web_session' | 'web_click' | 'short_link_click' | 'first_seen' | 'sms_aborted' | 'sms_delivered' | 'sms_dispatched' | 'sms_expired' | 'sms_failed' | 'sms_rejected' | 'sms_undeliverable' | 'sms_unknown' | 'email_bounce' | 'email_click' | 'email_delay' | 'email_delivered' | 'email_injection' | 'email_open' | 'email_unsubscribe' | 'scene_displayed' | 'scene_completed' | 'scene_incomplete' | 'survey_displayed' | 'survey_submitted' | 'survey_not_submitted', required: The target event activity, e.g., `app_open`. Default event values are enumerated below. If you create a custom or predefined event that you wish to segment users on, you must register the event in the Airship dashboard. See [Adding events to your project](/guides/audience/events/adding/). - `after` union: A date value for an absolute comparison or an integer value for a relative comparison. - … - `before` union: A date value for an absolute comparison or an integer value for a relative comparison. - … - `metric` 'count' | 'total_value' | 'last' | 'first': The metric you are targeting for the event. When using the metric `count` or `total_value`, `operator` and `value` are required. When using either `first` or `last`, `operator` and `value` are not allowed. Use one of the following combinations instead: * `before`/`precision` * `after`/`precision` * `on`/`on_precision` | Metric | Description | |---|---| | `count` | Evaluate based on the number of event occurrences. | | `total_value` | Evaluate based on the cumulative event `value` associated with the target user. | | `last` | Evaluate based on the last occurrence of an event for a given user/time window. | | `first` | Evaluate based on the first occurrence of an event for a given user/time window. | - `on` string, date-time: A [date-time](/developer/rest-api/ua/introduction/#date-time-format). - `on_precision` 'day' | 'month' | 'month_day' | 'year_month' | 'year_month_day': When using the `first` or `last` metric with the `on` property to target events on. For example, for the 5th of any month, or only in March, use `on_precision`. - `operator` 'greater' | 'less' | 'equals' | 'greater_eq' | 'less_eq', required: The comparison operator used to evaluate the activity expression. Use these operators (greater/less than, equal to, equal or greater/equal or less) when the `metric` is either `count` or `total_value`. - `precision` 'days' | 'weeks' | 'months' | 'years': If using a relative number (integer) for the `before`/`after`/`on` property, the `precision` value will be interpreted as the number of time units ago, e.g., *7 days ago*. Defaults to `days`. - `value` number, required: The value that the `operator` uses to evaluate the target audience. - `where` WhereObject: `where` is an object that filters on the existence of prior user activity, specified by event properties that you provide. - … - object: The request payload must be a JSON object with the following fields. - `NOT` union - union: Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. - object: AND selector - `AND` union[] - union - … - object: OR selector - `OR` union[] - union - … - object: NOT selector - `NOT` union - CompoundSelector (recursive) - union: Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a channel ID or metadata that maps to the device (or multiple devices) such as a tag. - … - union: Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a channel ID or metadata that maps to the device (or multiple devices) such as a tag. - object: A tag is an arbitrary bit of metadata used for targeting devices. A tag specifier may or may not have an associated group declaration, indicating a `tag group` the tag belongs to, for example, `{"tag": "silver-member", "group": "loyalty"}`. If no tag group is specified, the default `device` group is used. - `group` string - `tag` union, required - string - string[] - object: The segment ID. - `segment` union, required - string, uuid - string[] - object: The unique channel identifier used to target an open channel device or web device, i.e., web browser. - `channel` union, required - string, uuid - string[] - object: A `named_user` is an alternate, non-unique name, mapped to a user profile in a different database, e.g., CRM, that can be used to target devices associated with that profile. - `named_user` union, required - string - string[] - object: The unique channel identifier used to target a Fire OS device. - `amazon_channel` union, required - string, uuid - string[] - object: The unique channel identifier used to target an Android device. - `android_channel` union, required - string, uuid - string[] - object: The unique channel identifier used to target a device on an open platform. - `open_channel` union, required - string, uuid - string[] - object: Selects a single SMS device. The `msisdn` must be `opted_in` to receive notifications. - `msisdn` string, required: The recipient phone number. - `sender` string, required: The sender that the app is configured to send SMS messages from. - object: A `static_list` is a subset of your audience defined by a CSV file containing channel IDs or named users. - `static_list` union, required - string - string[] - object: An single instance or array of subscription list IDs. - `subscription_list` union, required - string - SubscriptionListId[] - object: An attribute object with a `TEXT` schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or named user. - `attribute` string, required: The key for the text attribute that you previously defined in the Airship UI, e.g., `"item_purchased"`. - `operator` 'equals' | 'contains' | 'less' | 'greater' | 'is_empty', required: The operator used to evaluate the attribute expression. - `value` string, required: The string you want to match when evaluating the attribute expression, e.g., `"jeans"`. - object: An attribute object with a `NUMBER` schema type. Performs value comparisons based on the number value for an attribute on a channel or named user. - `attribute` string, required: The key for the number attribute that you previously defined in the Airship UI, e.g., `"lifetime_value"`. - `operator` 'equals' | 'contains' | 'less' | 'greater' | 'is_empty', required: The operator used to evaluate the attribute expression. - `value` number, required: The value of the number attribute that you are targeting. For example, `15000`. - object: An attribute object with a `DATE` schema type. Performs absolute date comparisons for ISO-formatted date values or a relative date comparisons given an integer `value` and `precision`, e.g., `days`, `months`. Use a date attribute to target a channel or named user based on the date values. - `attribute` string, required: The key for the date attribute that you previously defined in the Airship UI, e.g., `"birth_date"`. - `operator` 'is_empty' | 'before' | 'after' | 'range' | 'equals', required: The operator used to evaluate the attribute expression. The `operator` that you use with a date attribute will determine which additional properties will be required in the object. See table for required fields. | Operator | Required properties | |---|---| | `is_empty` | `attribute` | | `before` | `attribute`, `value`, `precision`\* | | `after` | `attribute`, `value`, `precision`\* | | `range` | `attribute`, `value` | | `equals` | `attribute`, `value`, `precision`\*\* | \* *`precision` is required, but enum values are different than with an equals operator* \*\* *`precision` is required, but enum values are different than with a before or after operator* **Date Attribute Operators**: * `is_empty`— Evaluates to true if a channel or named user does not have a value for the attribute. * `before`— Value is one of: - *String*, ISO 8601 inclusive date, optionally including an offset, e.g., `2007-03-01T13:00:00+08:00`. The value will be converted and stored as UTC. - *Integer*, Relative number of units from the current time (i.e., now) into the past. Example: `"before": 20` indicates "at least 20 years ago" given a `precision` of `years`. - *String* with the value `"now"`, representing the current date-time, i.e., "before now". When using the `now` value, no `precision` is required. **Note**: When using the `before` operator, precision value must be one of `years`, `months`, `days`, `hours`, or `minutes`. * `after`— Values for `after` behave identically to `before`, as described above. * `range`— An ISO 8601 time interval. The format consists of an inclusive start and an exclusive end time date separated with a `/`, e.g., `2019-03-01T13:00:00/2019-05-11T15:30:00`. `range` does not have a precision. * `equals`— allows for selecting specific or non-specific dates as determined by the `precision` provided in the attribute object. **Note**: When using the `equals` operator, `precision` must be one of: - `day` — an integer which represents the day of the month or "now". - `month` — an integer which represents the month of the year starting with 1 for Jan or "now" which will use the value of the current month. - `month_day` — a string in the format of "mm-dd" which represents a month and day. Ex. 05-04 is May 4th. Value can also be "now". If today is 2020-03-09, then value will be "03-09". - `year_month` — a string in the format of "yyyy-mm" which represents a year and month. Ex. 2020-05 is May 2020. Value can also be "now". If today is 2020-03-09, then value will be "2020-03". - `year_month_day` — a string in the format of "yyyy-mm-dd" which represents a specific year, month, and day. Ex. 2020-05-04. Value can also be "now". If today is 2020-03-09, then value will be "2020-03-09". - or value can be "now" which is the current date-time. - `precision` 'years' | 'months' | 'days' | 'hours' | 'minutes' | 'day' | 'month' | 'month_day' | 'year_month' | 'year_month_day': The precision, expressed as a timing interval unit, that Airship uses to evaluate a date attribute expression. - `relative_to` 'future' | 'past': Specifies whether the date is in the `future` or in the `past`. If missing, it defaults to `past`. - `value` union - string, date-time: A [date-time](/developer/rest-api/ua/introduction/#date-time-format). - integer: An integer specifying the relative number of units, e.g., `days`, `years`, from the current time into the past. - object: An attribute object with a `JSON` schema type. Performs value comparisons based on the JSON value for an attribute on a channel or named user. - `attribute` string, required: The name of the attribute. - `where` object, required: An object that filters on the JsonPath expression that you provide. - `compare_as` 'text' | 'number' | 'date' | 'boolean': Selects the property type for comparison. - `operator` 'equals' | 'contains' | 'not_contains' | 'less' | 'less_eq' | 'greater' | 'greater_eq' | 'range' | 'before' | 'after' | 'is_empty' | 'not_empty', required: The operator used to evaluate the attribute expression. If the JsonPath expression maps to an array, the only available operators are `is_empty`, `not_empty`, `contains`, or `not_contains`. - `precision` 'minutes' | 'days' | 'months' | 'years': Used only for date values. - `property` string, required: The JsonPath expression that will be used to look up the value in a predefined attribute, for example `"$.x['store']['book'][0]['title']"`. This is different from selecting based on primitive string attributes, because the JsonPath expression can map to a single attribute or an array of attributes. See [JsonPath](https://github.com/json-path/JsonPath) for more information about JsonPath expressions and usage. - `relative_to` 'future' | 'past': Used only for date values. - `value` union: The value of the property you are filtering for in the `where` object. Use `compare_as` to select the type for comparison. This is required for all operators except `is_empty` and `not_empty`. - … - object: The `activity` object defines the target audience based on lifecycle actions or custom event activity, using comparison operators on activity count and recency. Optionally include a `where` object, which filters for specific activity values. In the example to the right, the target audience is users who have opened your app from a notification from the "neowise" campaign at least twice, 3 days ago. - `activity` 'app_open' | 'message_received' | 'message_center_read' | 'message_center_delivered' | 'message_center_deleted' | 'in_app_message_display' | 'in_app_message_resolution' | 'in_app_message_expiration' | 'screen_view' | 'web_session' | 'web_click' | 'short_link_click' | 'first_seen' | 'sms_aborted' | 'sms_delivered' | 'sms_dispatched' | 'sms_expired' | 'sms_failed' | 'sms_rejected' | 'sms_undeliverable' | 'sms_unknown' | 'email_bounce' | 'email_click' | 'email_delay' | 'email_delivered' | 'email_injection' | 'email_open' | 'email_unsubscribe' | 'scene_displayed' | 'scene_completed' | 'scene_incomplete' | 'survey_displayed' | 'survey_submitted' | 'survey_not_submitted', required: The target event activity, e.g., `app_open`. Default event values are enumerated below. If you create a custom or predefined event that you wish to segment users on, you must register the event in the Airship dashboard. See [Adding events to your project](/guides/audience/events/adding/). - `after` union: A date value for an absolute comparison or an integer value for a relative comparison. - string, date-time: A [date-time](/developer/rest-api/ua/introduction/#date-time-format), for example: `"after": "2020-08-01T12:00:00"`. - integer - `before` union: A date value for an absolute comparison or an integer value for a relative comparison. - string, date-time: A [date-time](/developer/rest-api/ua/introduction/#date-time-format), for example: `"before": "2020-08-01T12:00:00"`. - integer - `metric` 'count' | 'total_value' | 'last' | 'first': The metric you are targeting for the event. When using the metric `count` or `total_value`, `operator` and `value` are required. When using either `first` or `last`, `operator` and `value` are not allowed. Use one of the following combinations instead: * `before`/`precision` * `after`/`precision` * `on`/`on_precision` | Metric | Description | |---|---| | `count` | Evaluate based on the number of event occurrences. | | `total_value` | Evaluate based on the cumulative event `value` associated with the target user. | | `last` | Evaluate based on the last occurrence of an event for a given user/time window. | | `first` | Evaluate based on the first occurrence of an event for a given user/time window. | - `on` string, date-time: A [date-time](/developer/rest-api/ua/introduction/#date-time-format). - `on_precision` 'day' | 'month' | 'month_day' | 'year_month' | 'year_month_day': When using the `first` or `last` metric with the `on` property to target events on. For example, for the 5th of any month, or only in March, use `on_precision`. - `operator` 'greater' | 'less' | 'equals' | 'greater_eq' | 'less_eq', required: The comparison operator used to evaluate the activity expression. Use these operators (greater/less than, equal to, equal or greater/equal or less) when the `metric` is either `count` or `total_value`. - `precision` 'days' | 'weeks' | 'months' | 'years': If using a relative number (integer) for the `before`/`after`/`on` property, the `precision` value will be interpreted as the number of time units ago, e.g., *7 days ago*. Defaults to `days`. - `value` number, required: The value that the `operator` uses to evaluate the target audience. - `where` WhereObject: `where` is an object that filters on the existence of prior user activity, specified by event properties that you provide. - `compare_as` 'text' | 'number' | 'date' | 'boolean': Selects the property type for comparison. - `operator` 'greater' | 'less' | 'equals' | 'greater_eq' | 'less_eq' | 'contains' | 'present' | 'range' | 'before' | 'after', required: The operator in question - `precision` 'minutes' | 'days' | 'months' | 'years': Used only for date values. - `property` string, required: The custom event property on which to filter for inclusion in the audience. See the [Events Reference](/reference/data-collection/events/). - `relative_to` 'future' | 'past': Used only for date values. - `value` union, required: The value of the property you are filtering for in the `where` object. Use `compare_as` to select the type for comparison. - … ## Response `202` Returns OK for success. - OkResponseObject: Returned with 2xx Responses. At a minimum, successful calls return `true` for the `ok` key. If your call includes a verbose response (as with `GET` requests, etc.), the `ok` key will appear in the top-most object, outside the verbose response. - `ok` boolean, required: Success. - `operation_id` string, uuid: A unique string identifying the operations that modify resources. Use the operation ID to locate and track grouped operations (i.e., a batch push operation may generate multiple `push_id` strings, but a single `operation_id`) or operations that change an existing resource. ## Other responses - `400`: There was a parsing or validation error in the request. Bad Request errors typically include `path` and `location` in the response to help you find the cause of the error. - `401`: Authentication information (the app key and secret or bearer token) was either incorrect or missing. ## Changes - **2026-08-20** `bd6ab947117a`: 1 breaking - removed `subschema #1: Channel Subscription List action` from the `allOf[subschema #2: Subscription Lists -> subschema #2: Subscription lists]/items/action` request property `oneOf` list - …this revision’s changelog is incomplete - …earlier changes not shown [Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/channels/subscription_lists/post.md) --- [API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)