---
title: "Channel listing"
method: GET
path: "/api/channels"
tags: ["Channels"]
---

# Channel listing

`GET /api/channels`

## Request

- Base URL: `https://go.urbanairship.com`
- URL: `https://go.urbanairship.com/api/channels`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `http://oauth2.{domain}.com/token` scopes: `chn`
- TypeScript: <https://skmtc.dev/airship/apis/airship-api/docs/api/channels/get.ts> (a function with typed inputs; its response is checked against the schema)

List all channels registered to this app key, along with associated data and metadata.

## Query parameters

- `limit` integer

## Response `200`

Returns OK for success with the JSON response. Tags added to a channel using `/named_users/tags` are not returned from this endpoint. To view those tags, you must look up the named user associated with the channel.

- object
  - `channels` ChannelListingObject[]: An array of channel objects.
    - `address` string: The address to send push notifications to when `device_type` is `email` or `open`. For all other `device_type` values, this key is replaced with `push_address`.
    - `attributes` Attributes: Attributes associated with a channel or named user. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign. This object enumerates predefined attributes, but you can [create your own in the Airship dashboard](/guides/audience/attributes/adding/).
      - `account_creation` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the user created their account.
      - `advertising_id` string: The IDFA associated with a user.
      - `age` integer: The user's age.
      - `altitude` number: The altitude associated with a user.
      - `birthdate` string: The user's birthdate.
      - `city` string: The city associated with the user.
      - `company` string: The company that a user is associated with.
      - `country` string: The country associated with the user.
      - `email` string: A user's email address.
      - `first_name` string: The first name of a user.
      - `full_name` string: A user's first and last names.
      - `gender` string: A user's gender.
      - `home_phone` integer: The user's home phone number — similar to an SMS channel `msisdn`.
      - `last_name` string: The last name of a user.
      - `latitude` number: The latitude associated with a user — maybe their default location.
      - `longitude` number: The longitude associated with a user — maybe their default location.
      - `loyalty_tier` string: The loyalty program tier that a user is associated with, e.g., gold, platinum, etc.
      - `mobile_phone` integer: The user's mobile phone number — similar to an SMS channel `msisdn`.
      - `region` string: The state, province, principality, etc. associated with the user.
      - `title` string: A default attribute. You must enable this attribute in the dashboard before you can assign it.
      - `username` string: A user's username — generally a part of their login information.
      - `work_phone` integer: The user's work phone number — similar to an SMS channel `msisdn`.
      - `zipcode` integer: A user's zipcode. This is different from the SMS channel `ua_ndc` attribute, that records user's area code or phone number prefix.
    - `background` boolean: If true, the device can receive background push notifications. If false, it cannot. This field only appears for iOS devices.
    - `channel_id` string, uuid: The unique channel identifier for a device.
    - `commercial_opted_in` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive commercial emails.
    - `commercial_opted_out` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user explicitly denied permission to receive commercial emails.
    - `created` string, date-time: The creation [date-time](/developer/rest-api/ua/introduction/#date-time-format) of this channel.
    - `device_attributes` DeviceAttributes: Native attribute properties that Airship gathers automatically assigns to a channel. Varies by channel type. See [Default attributes](/reference/data-collection/attributes/#default-attributes). For segmentation, when using `ua_app_version`, `ua_sdk_version`, or `ua_device_os`, only semantic versioning formatting is accepted, and anything after the third decimal place is excluded, e.g., `12.2.3-alpha` is compared as `12.2.3`. You can use operators `equals`, `contains`, `less`, `greater`, `is_empty` with values in the formats `1`, `1.2`, `1.2.3`.
      - `ua_app_version` string: The app version that the channel uses.
      - `ua_browser_name` string: The browser associated with a web channel.
      - `ua_browser_type` 'mobile' | 'desktop': The browser type associated with a web channel.
      - `ua_browser_version` string: The browser version associated with a web channel.
      - `ua_carrier` string: The cellular carrier of the device associated with an app channel.
      - `ua_country` string: The 2-letter country code for an app or web channel.
      - `ua_country_code` string: The country dialing code derived from the MSISDN associated with an SMS channel.
      - `ua_device_model` string: The model of the device associated with an app channel.
      - `ua_device_os` string: The operating system of the device associated with an app channel.
      - `ua_email_domain` string: The portion of the email address after the `@` symbol for an email channel, such as `example.com`. Not set when a user is opted in by default, such as for transactional messages.
      - `ua_language` string: The 2-letter language code for an app or web channel.
      - `ua_local_tz` string: The time zone that the SDK registers for an app or web channel.
      - `ua_location_settings` 'true' | 'false': If `true`, location settings are enabled for an app channel.
      - `ua_ndc` string: The National Destination Code aka area code derived from the MSISDN on an SMS channel.
      - `ua_rcs_enabled` 'true': Rich Communication Services (RCS) capability for an SMS channel. Set to `true` when an RCS upgrade delivery receipt is received.
      - `ua_sdk_version` string: The Airship SDK version associated with an app or web channel.
      - `ua_subdivision` string: The ISO 3166-2 code derived from the MSISDN on an SMS channel.
    - `device_type` 'ios' | 'android' | 'amazon' | 'web' | 'open' | 'email' | 'sms': Specifies the device platform for a channel.
    - `email_address` string: The email address associated with the email channel when `device_type` is `email`.
    - `installed` boolean: If true, the channel is installed. If false, it is uninstalled.
    - `ios` IOSChannelObject: Contains parameters that apply when the `device_type` is set to `ios`.
      - `badge` integer: The iOS badge number. Must be greater than zero.
      - `quiettime` object: Quiet time settings. Requires presence of `tz`.
        - `end` string, nullable: Quiet time end in `HH:MM` format.
        - `start` string, nullable: Quiet time start in `HH:MM` format.
      - `scheduled_summary` boolean: If true, the scheduled summary notification status is enabled.
      - `time_sensitive` boolean: If true, the time sensitive notification status is enabled.
      - `tz` string, nullable: The channel's time zone. A list of possible time zone values is maintained at the [IANA Time Zone Database](http://www.iana.org/time-zones).
    - `last_registration` string, date-time, nullable: The last registration [date-time](/developer/rest-api/ua/introduction/#date-time-format) of this channel, if known.
    - `msisdn` string: The phone number associated with the SMS channel. Must be numeric characters only, without leading zeros.
    - `named_user_id` string, nullable: A customer-chosen ID that represents the device user, e.g., CRM ID. This ID cannot have leading or trailing whitespace. Listed as `null` when not set.
    - `open` OpenChannelOptionsObject: Contains options that apply when the `device_type` is set to `open`.
      - `identifiers` object: A set of up to 100 key:value pairs representing identifiers for this channel in your own delivery systems and delivered as a part of webhook payloads.
      - `old_address` string: If a channel exists for the value of `old_address`, replaces that channel's address with the value of `address`. Use infrequently, such as when an end user's phone number or email address permanently changes.
      - `open_platform_name` string, required: The name of the open channel that this `channel_id` is registered on.
    - `opt_in` boolean: If true, the channel is opted in to push notifications. If false, it is not. Required for all types except email.
    - `opt_in_date` string, date-time: `(SMS only)` The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the SMS channel gave permission to receive messages.
    - `opt_out_date` string, date-time: `(SMS only)` The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the SMS channel opted out of receiving messages.
    - `push_address` string, nullable: Required if `opt_in` is true. The address to send push notifications to for all `device_type` values other than `email` and `open`. When `device_type` is `email` or `open`, this key is replaced with `address`.
    - `subscription_lists` SubscriptionListObject[]: Lists all the subscription lists that this channel is subscribed to.
      - `action` union, required
        - object: Alters subscription list membership for a channel.
          - `action` 'subscribe' | 'unsubscribe', required: A string representing the membership mutation action to be taken for a given list.
          - `list_id` string, required: A list ID that contains only alphanumeric characters, underscores, or hyphens.
          - `type` 'channel', required
        - object: Alters subscription list membership for a contact.
          - `action` 'subscribe' | 'unsubscribe', required: A string representing the membership mutation action to be taken for a given list.
          - `list_id` string, required: A list ID that contains only alphanumeric characters, underscores, or hyphens.
          - `scope` 'app' | 'web' | 'email' | 'sms', required: The channel types where membership applies. The `app` scope includes `iOS`, `Android`, and `Amazon` channels.
          - `type` 'contact', required
      - `list_id` string, required: A list ID that contains only alphanumeric characters, underscores, or hyphens.
      - `timestamp` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the attribute changed. Server time is used when not present.
    - `suppression_state` 'spam_complaint' | 'commercial_spam_complaint' | 'bounce' | 'imported' | 'carrier_deactivation': The reason an email or SMS channel is suppressed. Suppressed channels don't receive messages. - `spam_complaint`, `commercial_spam_complaint`, `bounce`, and `imported` are email only. See [Email Bounce Handling and Suppression](/developer/api-integrations/email/bounce-handling/). - `carrier_deactivation` is SMS only. It is set when Airship's nightly carrier deactivation scan suppresses the channel. See [Suppression](/developer/api-integrations/sms/opt-in-out-handling#suppression) in *SMS Opt-In/Out Handling*.
    - `tag_groups` TagGroupObject: Tag groups appear within the `tags` object for a named user or the `tag_groups` object for a channel. `ua_` is a reserved prefix for Airship-specific tag groups. See [Device property tags](/reference/data-collection/device-property-tags/).
    - `tags` string[]
    - `transactional_opted_in` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.
    - `transactional_opted_out` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user explicitly denied permission to receive transactional emails.
    - `web` object: Contains parameters that apply when the `device_type` is set to `web`.
      - `subscription` object: The web subscription. This optional field is not present for cases where a browser is registered (for purposes of feature flags) but isn't opted-in to push notifications.
        - `keys` object: Encryption keys required for signing the push package.
          - `auth` string: The authentication secret.
          - `p256dh` string: The public key.
      - `user_agent_string` string: The full user agent string.
  - `next_page` string, url: If there is more than one page of results, use this link to get the next page of results.
  - `ok` boolean: Success.

## Other responses

- `401`: Authentication information (the app key and secret or bearer token) was either incorrect or missing.
- `404`: The requested resource doesn't exist.

## Changes

- **2026-08-20** `bd6ab947117a`: 1 breaking
  - added `subschema #1: Channel subscription list action` to the `channels/items/subscription_lists/items/action` response property `oneOf` list for the response status `200`
  - …this revision’s changelog is incomplete
- **2026-06-24** `38241778b0c1`: 1 warning
  - removed the optional property `channels/items/alias` from the response with the `200` status
  - …this revision’s changelog is incomplete
- **2026-02-20** `e2bd980cb50b`: 1 info
  - added the optional property `channels/items/device_attributes/ua_rcs_enabled` to the response with the `200` status

[Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/channels/get.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)