BitlyDeveloper
Start Now
Navigation

Migrating from V3

The latest version of the Bitly API is V4. For customers migrating from V3, this documentation will highlight some of the changes that we’ve made and how to adapt your integration to work with V4.

Authentication

How you authenticate to the Bitly API has changed with V4. Previously your authentication token would be provided as the access_token query parameter on each request. V4 instead requires that the token be provided as part of the Authorization header on each request. For example: 'Authorization: Bearer {token}'

For full details on requesting an access token via the API, please see the documentation here.

Group Aware

With Group Permissions, Bitly links and other data elements roll up into a group. In V3 you were required to generate a different OAuth token to view each group’s data, but in V4 you can provide the group GUID as part of the request.

If you’re not subscribed to the Enterprise plan, you only have a single group associated with your account. If you’re an Enterprise customer, you may have multiple groups associated with your account.

It's important to provide the group GUID for the correct Enterprise group, otherwise you may impede your workflow by pointing to a group with lower rate limits. Users can also set their default group in Bitly. To change the default group, sign in to Bitly, open the profile menu, select Settings, click Integrations, choose the default group and click Save changes.

Your groups can be retrieved via the following request:

GET https://api-ssl.bitly.com/v4/groups HTTP/1.1
Host: api-ssl.bitly.com
Authorization: Bearer {ACCESS_TOKEN}
Accept: application/json

Some endpoints within the application, especially those dealing with Bitly links and metrics, will require a group GUID to request the data. For example, to request all the links for a group requires the following request:

GET https://api-ssl.bitly.com/v4/groups/GUID/bitlinks HTTP/1.1
Host: api-ssl.bitly.com
Authorization: Bearer ACCESS_TOKEN

The API also provides a default group GUID for the user. There are endpoints and an in-app setting available to set this default group GUID. To change the user's default group in-app, sign in to Bitly, open the profile menu, select Settings, click Integrations, choose the default group and click Save changes.

The default group is used when a group GUID is not provided on shortening calls. The default group GUID is only used for shortening endpoints.

Even if you are a subscriber to the Free Bitly plan, the group GUID will still be required in these requests.

RESTfulness

The Bitly V4 API follows the more standard REST convention of utilizing the HTTP response codes to identify the status of the response. These include, but are not limited to:

  • 200 - SUCCESS
  • 400 - INVALID
  • 403 - FORBIDDEN
  • 404 - NOT FOUND
  • 500 - INTERNAL ERROR

In addition, V4 makes better use of the various methods for submitting data. GET requests will return data, POST requests are for creation, PATCH requests are for modification and DELETE requests are for removal.

A major difference is how the data is delivered. Under V3 responses were contained in a data envelope and would look like this:

{
  “status_code”: 200,
  “status_text”: “SUCCESS”,
  “data”: {
  //response data object
  }
}

V4 instead returns a JSON object containing all the data provided by the response. For example a standard Bitly link response is structured like this:

{
  "references": {
    "property1": "string",
    "property2": "string"
  },
  "archived": true,
  "tags": [
    "string"
  ],
  "created_at": "string",
  "title": "string",
  "deeplinks": [
    {
      "bitlink": "string",
      "install_url": "string",
      "created": "string",
      "app_uri_path": "string",
      "modified": "string",
      "install_type": "string",
      "app_guid": "string",
      "guid": "string",
      "os": "string"
    }
  ],
  "created_by": "string",
  "long_url": "string",
  "custom_bitlinks": [
    "string"
  ],
  "link": "string",
  "id": "string"
}

V4 has also simplified how much data is returned on an individual request. Because of the nested nature of some of our data and to improve the overall performance of the API we include a collection of references which provide request URLs for returning additional data. For example, here is the references collection for a Bitlink:

"references":{
  "group":"https://api-ssl.bitly.com/v4/groups/GUID"
}

Instead of nesting the full Group object and any additional objects it may reference, this request URL is provided to retrieve that additional data if required.