Shorten & Customize Links

Types of short links

There are four types of short links that can be created in Bitly. The more customized the link, the more parameters you'll need to pass through in the call.

Both the domain and the back-half of a short link can be customized to some extent, depending on your subscription plan.

Custom link (sometimes "custom branded link")
https://yourdomain.co/newsupdate
A custom domain and a customized back-half

Branded link
https://yourdomain.co/5x4tprm
A custom domain, but no customized back-half

Short link with a custom back-half
https://bit.ly/newsupdate
Bitly's generic domain, with a customized back-half

Bitly short link
https://bit.ly/2dt1pnm_
Bitly's generic domain, no customized back-half

Creating Bitly short links

The most basic call to shorten a link is using the POST method to the /v4/shorten endpoint. There is only one customization available through this call, and that's using your custom domain. If a custom domain is not specified, the resulting short link will default to bit.ly.

POST /v4/shorten

{
      "group_guid": "Ba1bc23dE4F",
      "domain": "bit.ly",
      "long_url": "https://dev.bitly.com"
}

A successful response will return the shortened link in the link object.

{
  "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",
      "brand_guid": "string"
    }
  ],
  "created_by": "string",
  "long_url": "string",
  "client_id": "string",
  "custom_bitlinks": [
    "string"
  ],
  "link": "string",
  "id": "string"
}

Creating custom links

Customizing links can stretch beyond simply using a custom domain. These more complex customizations use the POST method to the /bitlinks endpoint.

To customize a short link, you'll need to provide more fields in the request body. Additionally, you can extend the power of the link through other parameters. To customize the back-half of a link, you'll perform an additional PATCH call.

PATCH /v4/custom_bitlinks/{custom_bitlink}

domain
Customizing the domain requires that you have a custom domain attached to your Bitly account. The default value is bit.ly.

title
A short description that appears in the Bitly UI.

group_guid
Identifies a group of users in your account. Every user will belong to at least one group within an organization. Most actions on our API will be on behalf of a group. Always verify your default group in Bitly and specify a group in the call.

long_url The URL that will be shortened.

Include the necessary parameters to create the type of link.

POST /v4/bitlinks

{
  "domain": "bit.ly",
  "title": "Bitly API Documentation",
  "group_guid": "Ba1bc23dE4F",
  "long_url": "https://dev.bitly.com"
}

A successful response will return the shortened link in the link object.

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

Retrieve Bitlink

Metadata for an existing short link can be retrieved using a GET call.

GET /v4/bitlinks/{bitlink}

bitlink
The bitlink to retrieve information for. Eg: bit.ly/Gzmskv

Include the necessary parameters to create the type of link.

GET /v4/bitlinks/bit.ly/Gzmskv

A successful response will return the metadata associated with the short link.

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

The field custom_bitlinks returns the history of edited backhalfs associated with the short link.

Example response:

{
    "created_at": "2022-05-17T02:45:02+0000",
    "id": "bitly.org/GzmKSE",
    "link": "https://bitly.org/GzmKSE",
    "custom_bitlinks": [
        "https://bitly.org/GzmKSs",
        "https://bitly.org/customized1",
        "https://bitly.org/customized2",
        "https://bitly.org/customized3"
    ],
    "long_url": "http://anotherlink1111.com/",
    "archived": false,
    "created_by": "xxx",
    "client_id": "xxx",
    "tags": [],
    "deeplinks": [],
    "has_override": true,
    "references": {
        "group": "https://api-ssl.bitly.org/v4/groups/xxx",
        "overrides": "https://api-ssl.bitly.org/v4/bitlinks/bitly.org/GzmKSE/overrides"
    }
}

Delete Bitlink

An unedited short link can be deleted using a DELETE call. An unedited short link refers to bitlinks that have not had its back-half customized or have not had its destination long URL changed.

DELETE /v4/bitlinks/{bitlink}

bitlink
The bitlink to be deleted. Eg: bit.ly/Gzmskv

Include the necessary parameters to delete the hash link.

DELETE /v4/bitlinks/bit.ly/Gzmskv

A successful response will return the link that was deleted.

{
  "links_deleted": [
    {
      "id": "string"
    }
  ]
}

For the full list of endpoints and available parameters, view our API reference.