User Info / History

/v3/oauth/app

Return information about an OAuth app.

Authentication: oauth2

Parameters

  • client_id - the client ID of the app.

Return Values

  • client_id - the client ID of the app
  • app_name - the app's name
  • app_description - the app's description
  • app_link - a URL about the app

/v3/user/info

Return or update information about a user.

Authentication: oauth2

Parameters

  • login - (optional) the bitly login of the user whose info to look up. If not given, the authenticated user will be used.
  • full_name - (optional) set the users full name value. (only available for the authenticated user.)

Return Values

All requests

  • login - the specified bitly login or the login of the authenticated user.
  • profile_url - URL of user's profile page.
  • profile_image - URL of user's profile image.
  • member_since - Unix timestamp for the moment the user signed up.
  • full_name - (optional) the user's full name, if set.
  • display_name - (optional) the user's display name, if set.
  • share_accounts - (optional) a list of the share accounts (Twitter or Facebook) linked to the user's account.

Only included in requests for a user's own info

  • apiKey - the user's bitly API key.
  • is_enterprise - 0 or 1 to indicate if this account is signed up for Bitly Brand Tools.
  • has_master - 0 or 1 to indicate if this account is a customer sub account.
  • custom_short_domain - A short domain registered with this account that can be used in place of bit.ly for shortening links.
  • tracking_domains - A list of domains configured for analytics tracking.
  • default_link_privacy - public or private indicating the default privacy setting for new links.
  • domain_preference_options - A list of the valid short domains that this account can choose as a default.
Only included for enterprise accounts (is_enterprise == 1 or has_master == 1)
  • sub_accounts - (optional) list of accounts associated with this account.
  • e2e_domains - (optional) list of domains associated with this custom_short_domain.
  • tracking_url_prefxies - A list of owned 3rd party urls such as Facebook tracked for analytics
  • master_account - (optional) the login of a master account, if this is associated with an enterprise account.
  • enterprise_permissions - (optional) list of enterprise permissions associated with this account.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/info?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "apiKey": "R_f6397a37e765574f2e198dba5bb59522",
    "custom_short_domain": null,
    "display_name": null,
    "full_name": "Bitly API Oauth Demo Account",
    "is_enterprise": false,
    "login": "bitlyapioauthdemo",
    "member_since": 1331567982,
    "profile_image": "http://bitly.com/u/bitlyapioauthdemo.png",
    "profile_url": "http://bitly.com/u/bitlyapioauthdemo",
    "share_accounts": [],
    "tracking_domains": []
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/network_history

Returns entries from a user's network history in reverse chronogical order. (A user's network history includes publicly saved links from Twitter and Facebook connections.)

Authentication: oauth2

Parameters

  • offset - optional integer that specifies the first record to return.
  • expand_client_id - optional true or false whether to provide additional information about encoding application. default: false.
  • limit - optional integer in the range of 1 to 100 that specifies the number of records to return (default: 20).
  • expand_user - optional - true or false - include extra user info in response (login, avatar_url, display_name, profile_url, full_name).

Return Values

  • total - the total number of network history results returned.
  • limit - an echo back of the limit parameter.
  • offset - an echo back of the offset parameter.
  • entries - the returned network history links. Each link includes:
    • global_hash -the global (aggregate) identifier of this link.
    • saves - information about each time this link has been publicly saved by bitly users followed by the authenticated user. Each save returns:
      • link - the bitly link specific to this user and this long_url.
      • aggregate_link - the global bitly identifier for this long_url.
      • long_url - the original long URL.
      • user - the bitly user who saved this link.
      • archived - a true/false value indicating whether the user has archived this link.
      • private - a true/false value indicating whether the user has made this link private.
      • created_at - an integer unix epoch indicating when this link was shortened/encoded.
      • user_ts - a user-provided timestamp for when this link was shortened/encoded, used for backfilling data.
      • modified_at - an integer unix epoch indicating when this link's metadata was last edited.
      • title - the title for this link.
      • client_id - the oauth client ID of the app that shortened/saved this link on behalf of the user. If expand_client_id is set to false, this will be a string corresponding to the client_id of the encoding oauth application. If expand_client_id is set to true, this will be a mapping containing the following fields:
        • client_id - a string corresponding to the client_id of the encoding oauth application.
        • app_link - the link for the encoding oauth application.
        • app_name - the name of the encoding oauth application.
        • app_description - a description of the encoding oauth application.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/network_history?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "entries": [
      {
        "global_hash": "789",
        "saves": [
          {
            "aggregate_link": "http://bit.ly/789",
            "archived": false,
            "client_id": "a5a2e024b030d6a594be866c7be57b5e2dff9972",
            "created_at": 1337892044,
            "global_hash": "789",
            "link": "http://bit.ly/123",
            "long_url": "http://fakewebsite.com/something",
            "modified_at": 1337892044,
            "private": false,
            "title": "This is a page about exciting things!",
            "user": "somebitlyuser",
            "user_ts": 1337892044
          }
        ]
      },
      {
        "global_hash": "234",
        "saves": [
          {
            "aggregate_link": "http://bit.ly/234",
            "archived": false,
            "client_id": "a5a2e024b030d6a594be866c7be57b5e2dff9972",
            "created_at": 1337892044,
            "global_hash": "234",
            "link": "http://bit.ly/567",
            "long_url": "http://something.com/blahblahblah",
            "modified_at": 1337892044,
            "private": false,
            "title": "This is an article about something!",
            "user": "anotherbitlyuser",
            "user_ts": 1337892044
          }
        ]
      }
    ],
    "limit": 20,
    "offset": 0,
    "total": 2
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/tracking_domain_list

Returns a list of tracking domains a user has configured.

Return Values

  • tracking_domains - a list of tracking domains configured for the authenticated user.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/tracking_domain_list?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "tracking_domains": [
      "usa.gov"
    ]
  },
  "status_code": 200,
  "status_txt": "OK"
}