POST lists/create

Creates a new list for the authenticated user. Note that you can create up to 1000 lists per account.

Resource URL

https://api.twitter.com/1.1/lists/create.json

Resource Information

Response formats JSON
Requires authentication? Yes
Rate limited? Yes

Parameters

Name Required Description Default Value Example
name required The name for the list. A list's name must start with a letter and can consist only of 25 or fewer letters, numbers, "-", or "_" characters.
mode optional Whether your list is public or private. Values can be public or private . If no mode is specified the list will be public.
description optional The description to give the list.

Example Request

POST https://api.twitter.com/1.1/lists/create.json?name=Test%20List&mode=public&description=This%20is%20a%20test%20list

Example Response

{
  "id": 1130194503435018247,
  "id_str": "1130194503435018247",
  "name": "Test List",
  "uri": "/TwitterDev/lists/test-list",
  "subscriber_count": 0,
  "member_count": 0,
  "mode": "public",
  "description": "This is a test list",
  "slug": "test-list",
  "full_name": "@TwitterDev/test-list",
  "created_at": "Sun May 19 19:32:22 +0000 2019",
  "following": false,
  "user": {
    "id": 2244994945,
    "id_str": "2244994945",
    "name": "Twitter Dev",
    "screen_name": "TwitterDev",
    "location": "Internet",
    "description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https://t.co/mGHnxZU8c1 ⌨️ #TapIntoTwitter",
    "url": "https://t.co/FGl7VOULyL",
    "entities": {
      "url": {
        "urls": [
          {
            "url": "https://t.co/FGl7VOULyL",
            "expanded_url": "https://developer.twitter.com/",
            "display_url": "developer.twitter.com",
            "indices": [
              0,
              23
            ]
          }
        ]
      },
      "description": {
        "urls": [
          {
            "url": "https://t.co/mGHnxZU8c1",
            "expanded_url": "https://twittercommunity.com/",
            "display_url": "twittercommunity.com",
            "indices": [
              93,
              116
            ]
          }
        ]
      }
    },
        "protected": false,
        "followers_count": 502084,
        "friends_count": 1472,
        "listed_count": 1514,
        "created_at": "Sat Dec 14 04:35:55 +0000 2013",
        "favourites_count": 2203,
        "utc_offset": null,
        "time_zone": null,
        "geo_enabled": true,
        "verified": true,
        "statuses_count": 3393,
        "lang": "en",
        "contributors_enabled": false,
        "is_translator": false,
        "is_translation_enabled": null,
        "profile_background_color": "null",
        "profile_background_image_url": "null",
        "profile_background_image_url_https": "null",
        "profile_background_tile": null,
        "profile_image_url": "null",
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1498675817",
        "profile_link_color": "null",
        "profile_sidebar_border_color": "null",
        "profile_sidebar_fill_color": "null",
        "profile_text_color": "null",
        "profile_use_background_image": false,
        "has_extended_profile": null,
        "default_profile": false,
        "default_profile_image": false,
        "following": false,
        "follow_request_sent": false,
        "notifications": false,
        "translator_type": "null"
  }
}