# Subscription Lists

Create, manage, and add or remove channels from subscription lists.


## Named User subscription lists listing {#getnamedusersubscriptionlists}

Provides the subscription lists that are associated with a given Named User.

[Jump to examples ↓](#getnamedusersubscriptionlists-examples)

### `GET /api/subscription_lists/named_users/{named_user_id}`

**Security:**

- [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth)
- [bearerAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-bearerAuth)
- [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-oauth2Token): nu

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `named_user_id` | `string` | Required | The Named User being looked up. |

**Responses**

**`200`** Returns OK for success, with the Named User subscription list IDs.

Response body:

**Content-Type:** `application/vnd.urbanairship+json; version=3`

- **`ok`** `boolean`

  Success.

- **`subscription_lists`** `array` <[Contact Subscription List object]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#contactsubscriptionlistobject)>
**`304`** An If-Modified-Since request header exists and the result is unchanged.

Response body:

**Content-Type:** `application/vnd.urbanairship+json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing.

Response body:

**Content-Type:** `text/plain`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**Examples**

*Example*

```http
GET /api/subscription_lists/named_users/4cbd1c1c-42e1-4606-bc93-9b707bcedcbc HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3

```

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true,
   "subscription_lists": [
      {
         "list_ids": ["example_listId-2", "example_listId-4"],
         "scope": "app"
      },
      {
         "list_ids": ["example_listId-2"],
         "scope": "web"
      }
   ],
}

```

```java
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

NamedUserSubscriptionListsListingRequest namedUserSubscriptionListsListingRequest = NamedUserSubscriptionListsListingRequest.newRequest("4cbd1c1c-42e1-4606-bc93-9b707bcedcbc");
Response<NamedUserSubscriptionListsListingResponse> response = client.execute(namedUserSubscriptionListsListingRequest);

```

```python
from urbanairship import (
    BasicAuthClient, SubscriptionList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Get subscription lists for a named user
named_user_lists = SubscriptionList(client).list_by_named_user('4cbd1c1c-42e1-4606-bc93-9b707bcedcbc')

```

---

## Subscription lists listing {#getsubscriptionlists}

Provides a list of subscription lists IDs that are associated with this app key.

[Jump to examples ↓](#getsubscriptionlists-examples)

### `GET /api/subscription_lists`

**Security:**

- [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth)
- [bearerAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-bearerAuth)
- [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-oauth2Token): lst

**Responses**

**`200`** Returns OK for success, with the list of subscription lists for the app.

Response body:

**Content-Type:** `application/vnd.urbanairship+json; version=3`

- **`ok`** `boolean`

  Success.

- **`subscription_lists`** `array` <[Subscription List result object]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistresultobject)>

  An array of subscription list result objects.

**`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing.

Response body:

**Content-Type:** `text/plain`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**Examples**

*Example*

```http
GET /api/subscription_lists HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3

```

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true,
   "subscription_lists": [
       {
           "list_id": "example_listId-1",
           "name": "A nice readable name 1",
           "scopes": ["email"],
           "messaging_type": "transactional",
           "default_opted_in": false
       },
       {
           "list_id": "example_listId-2",
           "name": "A nice readable name 2",
           "description": "A very nice description for you.",
           "scopes": ["app", "web"],
           "default_opted_in": true
       }
   ]
}

```

```java
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SubscriptionListListingRequest subscriptionListListingRequest = SubscriptionListListingRequest.newRequest();
Response<SubscriptionListListingResponse> response = client.execute(subscriptionListListingRequest);

```

```python
from urbanairship import (
    BasicAuthClient, SubscriptionList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# List all subscription lists
subscription_lists = SubscriptionList(client).list()

```

---