Skip to main content
BitlyDeveloper
Start Now
Bitly API (4.0.0)
OpenAPI Specification: Download

Bitlinks

Bitlinks are shortened links. They could begin with the bit.ly domain or your own custom branded short domain (BSD).

Shorten a Link

Post
/v4/shorten

Converts a long url to a Bitlink. You may see errors returned from this endpoint - "BRANDED_LINK_MONTHLY_LIMIT_EXCEEDED" occurs if you have shortened more links than your account is configured for for the month, and "DNS_CONFIGURATION_ERROR" occurs if you are attempting to shorten links against a custom domain which doesn't have DNS properly configured.

Request Body Schema

long_urlstringRequired
domainstring
Default: "bit.ly"
group_guidstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "long_url": "https://dev.bitly.com",
  "domain": "bit.ly",
  "group_guid": "Ba1bc23dE4F"
}' \
https://api-ssl.bitly.com/v4/shorten
{
  "references": { "any" },
  "link": "string",
  "id": "string",
  "long_url": "string",
  "archived": "boolean",
  "created_at": "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"
    }
  ]
}

Create a Bitlink

Post
/v4/bitlinks

Converts a long url to a Bitlink and sets additional parameters. You may see errors returned from this endpoint - "BRANDED_LINK_MONTHLY_LIMIT_EXCEEDED" occurs if you have shortened more links than your account is configured for for the month, and "DNS_CONFIGURATION_ERROR" occurs if you are attempting to shorten links against a custom domain which doesn't have DNS properly configured.

Request Body Schema

long_urlstringRequired
domainstring
Default: "bit.ly"
group_guidstring
Always include a specific group and custom domain in your shorten calls.
titlestring
tagsarray of string
deeplinksarray of object
app_idstring
app_uri_pathstring
install_urlstring
install_typestring
Enum: "no_install""auto_install""promote_install"
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "long_url": "https://dev.bitly.com",
  "domain": "bit.ly",
  "group_guid": "Ba1bc23dE4F",
  "title": "Bitly API Documentation",
  "tags": [
    "bitly",
    "api"
  ],
  "deeplinks": [
    {
      "app_id": "com.bitly.app",
      "app_uri_path": "/store?id=123456",
      "install_url": "https://play.google.com/store/apps/details?id=com.bitly.app&hl=en_US",
      "install_type": "promote_install"
    }
  ]
}' \
https://api-ssl.bitly.com/v4/bitlinks
{
  "references": { "any" },
  "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"
  ],
  "launchpad_ids": [
    "string"
  ],
  "qr_code_ids": [
    "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"
    }
  ],
  "campaign_ids": [
    "string"
  ]
}

Delete a Bitlink

Delete
/v4/bitlinks/{bitlink}

Delete an unedited hash Bitlink.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X DELETE \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c
{
  "links_deleted": [
    {
      "id": "string"
    }
  ]
}

Update a Bitlink

Patch
/v4/bitlinks/{bitlink}

Updates fields in the specified link. To redirect the link (i.e. to update the Long URL), use PATCH /v4/custom_bitlinks/{custom_bitlink} (https://dev.bitly.com/api-reference/#updateCustomBitlink)

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Request Body Schema

titlestring
archivedboolean
tagsarray of string
deeplinksarray of object
guidstring
bitlinkstring
app_uri_pathstring
install_urlstring
app_guidstring
osstring
Enum: "ios""android"
install_typestring
Enum: "no_install""auto_install""promote_install"
createdstring
ISO timestamp
modifiedstring
ISO timestamp
brand_guidstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "title": "Bitly API Documentation",
  "archived": false,
  "tags": [
    "bitly",
    "api"
  ],
  "deeplinks": [
    {
      "guid": "Ra1bcD2eF3h",
      "bitlink": "bit.ly/documentation",
      "app_uri_path": "/store?id=123456",
      "install_url": "https://play.google.com/store/apps/details?id=com.bitly.app&hl=en_US",
      "app_guid": "Ab1cdE2fG3h",
      "os": "android",
      "install_type": "promote_install",
      "brand_guid": "Ba1bc23dE4F"
    }
  ]
}' \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c
{
  "references": { "any" },
  "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"
  ],
  "launchpad_ids": [
    "string"
  ],
  "qr_code_ids": [
    "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"
    }
  ],
  "campaign_ids": [
    "string"
  ]
}

Retrieve a Bitlink

Get
/v4/bitlinks/{bitlink}

Returns information for the specified link.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c
{
  "references": { "any" },
  "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"
  ],
  "launchpad_ids": [
    "string"
  ],
  "qr_code_ids": [
    "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"
    }
  ],
  "campaign_ids": [
    "string"
  ]
}

Expand a Bitlink

Post
/v4/expand

Returns the short link and long URL for the specified link.

Request Body Schema

bitlink_idstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "bitlink_id": "bit.ly/12a4b6c"
}' \
https://api-ssl.bitly.com/v4/expand
{
  "link": "string",
  "id": "string",
  "long_url": "string",
  "created_at": "string"
}

Get Clicks for a Bitlink

Get
/v4/bitlinks/{bitlink}/clicks

Returns the click counts for the specified link in an array based on a date.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/clicks?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "link_clicks": [
    {
      "clicks": "integer",
      "date": "string"
    }
  ],
  "units": "integer",
  "unit": "string",
  "unit_reference": "string"
}

Get a Clicks Summary for a Bitlink

Get
/v4/bitlinks/{bitlink}/clicks/summary

Returns the click counts for the specified link rolled up into a single field.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/clicks/summary?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "total_clicks": "integer",
  "units": "integer",
  "unit": "string",
  "unit_reference": "string"
}

Get Metrics for a Bitlink by Country

Get
/v4/bitlinks/{bitlink}/countries

Returns the country origins of click traffic for the specified link.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/countries?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Metrics for a Bitlink by City

Get
/v4/bitlinks/{bitlink}/cities

Returns the city origins of click traffic for the specified link.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/cities?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "city": "string",
      "subregion": "string",
      "region": "string",
      "country": "string"
    }
  ],
  "other_metrics": {
    "other_city_clicks": "integer",
    "no_city_clicks": "integer"
  }
}

Get Metrics for a Bitlink by Device Type

Get
/v4/bitlinks/{bitlink}/devices

Returns the device types generating click traffic to the specified link.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/devices?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "device_type": "string"
    }
  ]
}

Get Metrics for a Bitlink by Referrers

Get
/v4/bitlinks/{bitlink}/referrers

Returns referrer click counts for the specified link.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/referrers?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Metrics for a Bitlink by Referrer Name

Get
/v4/bitlinks/{bitlink}/referrer_name

Returns referrer click counts for the specified link.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/referrer_name?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Metrics for a Bitlink by Referring Domains

Get
/v4/bitlinks/{bitlink}/referring_domains

Returns the referring domain click counts for the specified link.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/referring_domains?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Metrics for a Bitlink by Referrers by Domain

Get
/v4/bitlinks/{bitlink}/referrers_by_domains

Returns click metrics grouped by referrers for the specified link.

Path Parameters

bitlinkstringRequired
A Bitlink made of the domain and hash

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/referrers_by_domains?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "referrers_by_domain": [
    {
      "network": "string",
      "referrers": [
        {
          "key": "string",
          "value": "integer"
        }
      ]
    }
  ]
}

Retrieve Bitlinks by Group

Get
/v4/groups/{group_guid}/bitlinks

Returns a paginated collection of Bitlinks for a group. The list of custom bitlinks has newest entries first.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

sizeinteger
The quantity of items to be be returned
Default: 50
search_afterstring
Token used to search next batch, only use response from API as input value.
querystring
The value that you would like to search
created_beforeinteger
Timestamp as an integer unix epoch (seconds only)
created_afterinteger
Timestamp as an integer unix epoch (seconds only)
archivedstring
Whether or not to include archived resources
Default: "off"
Enum: "on""off""both"
deeplinksstring
Filter to only Bitlinks that contain deeplinks
Default: "both"
Enum: "on""off""both"
domain_deeplinksstring
Filter to only Bitlinks that contain deeplinks configured with a custom domain
Default: "both"
Enum: "on""off""both"
campaign_guidstring
Filter to return only links for the given campaign GUID, can be provided
channel_guidstring
Filter to return only links for the given channel GUID, can be provided, overrides all other parameters
custom_bitlinkstring
Default: "both"
Enum: "on""off""both"
has_qr_codesstring
a filter value if the resource has any QR codes
Default: "both"
Enum: "on""off""both"
tagsarray
Filter by given tags
launchpad_idsarray
Filter by launchpad id
encoding_loginarray
Filter by the login of the authenticated user that created the Bitlink
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/bitlinks?size=10&search_after=&query=api&created_before=1694529902&created_after=1694529902&archived=both&deeplinks=both&domain_deeplinks=both&campaign_guid=Ca1bcd2EFGh&channel_guid=Ha1bc2DefGh&custom_bitlink=both&has_qr_codes=both&tags=bitly&tags=api&launchpad_ids=M1234567890&encoding_login=chauncey
{
  "links": [
    {
      "references": { "any" },
      "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"
      ],
      "launchpad_ids": [
        "string"
      ],
      "qr_code_ids": [
        "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"
        }
      ],
      "campaign_ids": [
        "string"
      ]
    }
  ],
  "pagination": {
    "next": "string",
    "search_after": "string",
    "size": "integer"
  }
}

Bulk update bitlinks

Patch
/v4/groups/{group_guid}/bitlinks

Bulk update can add or remove tags or archive up to 100 links at a time; The response includes a list of bitlink ids that were updated.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Request Body Schema

actionstringRequired
archive or edit_tags
Enum: "archive""edit_tags"
archiveboolean
add_tagsarray of string
remove_tagsarray of string
linksarray of string
this is limited to 100 bitlink ids
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "action": "edit_tags",
  "add_tags": [
    "tag1",
    "tag2"
  ],
  "links": [
    "bit.ly/1234abcd",
    "bit.ly/5678efgh"
  ]
}' \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/bitlinks
{
  "links": [
    "string"
  ]
}

Retrieve Sorted Bitlinks for Group

Get
/v4/groups/{group_guid}/bitlinks/{sort}

Returns a list of Bitlinks sorted by group. The list of custom bitlinks has newest entries first.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group
sortstringRequired
The type of sorting that you would like to do
Enum: "clicks"

Query Parameters

unitstring
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsinteger
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
sizeinteger
The quantity of items to be be returned
Default: 50
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/bitlinks/clicks?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700&size=10
{
  "links": [
    {
      "references": { "any" },
      "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"
      ],
      "launchpad_ids": [
        "string"
      ],
      "qr_code_ids": [
        "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"
        }
      ],
      "campaign_ids": [
        "string"
      ]
    }
  ],
  "sorted_links": [
    {
      "clicks": "integer",
      "id": "string"
    }
  ]
}

BSDs

Branded short domains (BSDs) are the custom domains used to brand your links. A BSD can be added to a Bitly organization and may be assigned to one or more groups. They can contain up to 32 characters.

Get BSDs

Get
/v4/bsds

Fetch all Branded Short Domains

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bsds
{
  "bsds": [
    "string"
  ]
}

Campaigns

Bitly Campaigns are used to build and organize links and metrics for marketing campaigns.

Retrieve Campaigns

Get
/v4/campaigns

Returns the campaigns for the current authenticated user.

Query Parameters

group_guidstring
A GUID for a Bitly group
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/campaigns?group_guid=Ba1bc23dE4F
{
  "campaigns": [
    {
      "references": { "any" },
      "guid": "string",
      "group_guid": "string",
      "created_by": "string",
      "name": "string",
      "description": "string",
      "created": "string",
      "modified": "string"
    }
  ]
}

Create Campaign

Post
/v4/campaigns

Creates a new campaign.

Request Body Schema

group_guidstring
namestring
descriptionstring
channel_guidsarray of string
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "group_guid": "Ba1bc23dE4F",
  "name": "My Campaign",
  "description": "my new campaign",
  "channel_guids": [
    "Ha1bc2DefGj",
    "Ha1bc2DefGk"
  ]
}' \
https://api-ssl.bitly.com/v4/campaigns
{
  "references": { "any" },
  "guid": "string",
  "group_guid": "string",
  "created_by": "string",
  "name": "string",
  "description": "string",
  "created": "string",
  "modified": "string"
}

Retrieve a Campaign

Get
/v4/campaigns/{campaign_guid}

Returns details for a campaign.

Path Parameters

campaign_guidstringRequired
A GUID for a Bitly campaign
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/campaigns/Ca1bcd2EFGh
{
  "references": { "any" },
  "guid": "string",
  "group_guid": "string",
  "created_by": "string",
  "name": "string",
  "description": "string",
  "created": "string",
  "modified": "string"
}

Update Campaign

Patch
/v4/campaigns/{campaign_guid}

Updates a campaign's details.

Path Parameters

campaign_guidstringRequired
A GUID for a Bitly campaign

Request Body Schema

group_guidstring
namestring
descriptionstring
channel_guidsarray of string
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "group_guid": "Ba1bc23dE4F",
  "name": "My Campaign",
  "description": "my new campaign",
  "channel_guids": [
    "Ha1bc2DefGj",
    "Ha1bc2DefGk"
  ]
}' \
https://api-ssl.bitly.com/v4/campaigns/Ca1bcd2EFGh
{
  "references": { "any" },
  "guid": "string",
  "group_guid": "string",
  "created_by": "string",
  "name": "string",
  "description": "string",
  "created": "string",
  "modified": "string"
}

Retrieve Channels

Get
/v4/channels

Returns the channels available to a user.

Query Parameters

group_guidstring
A GUID for a Bitly group
campaign_guidstring
A GUID for a Bitly campaign
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/channels?group_guid=Ba1bc23dE4F&campaign_guid=Ca1bcd2EFGh
{
  "channels": [
    {
      "name": "string",
      "guid": "string",
      "created": "string",
      "modified": "string",
      "group_guid": "string",
      "references": { "any" }
    }
  ]
}

Create Channel

Post
/v4/channels

Creates a new channel.

Request Body Schema

namestring
guidstring
createdstring
ISO TIMESTAMP
modifiedstring
ISO_TIMESTAMP
group_guidstring
bitlinksarray of object
campaign_guidstring
bitlink_idstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "name": "My Channel",
  "guid": "Ha1bc2DefGh",
  "group_guid": "Ba1bc23dE4F",
  "bitlinks": [
    {
      "campaign_guid": "Ca1bcd2EFGh",
      "bitlink_id": "bit.ly/1234abcd"
    }
  ]
}' \
https://api-ssl.bitly.com/v4/channels
{
  "name": "string",
  "guid": "string",
  "created": "string",
  "modified": "string",
  "group_guid": "string",
  "references": { "any" }
}

Get a Channel

Get
/v4/channels/{channel_guid}

Returns a channel's details.

Path Parameters

channel_guidstringRequired
A GUID for a Bitly Channel
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/channels/Ha1bc2DefGh
{
  "name": "string",
  "guid": "string",
  "created": "string",
  "modified": "string",
  "group_guid": "string",
  "references": { "any" }
}

Update a Channel

Patch
/v4/channels/{channel_guid}

Updates an existing channel.

Path Parameters

channel_guidstringRequired
A GUID for a Bitly Channel

Request Body Schema

namestring
guidstring
createdstring
ISO TIMESTAMP
modifiedstring
ISO_TIMESTAMP
group_guidstring
bitlinksarray of object
campaign_guidstring
bitlink_idstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "name": "My Channel",
  "guid": "Ha1bc2DefGh",
  "group_guid": "Ba1bc23dE4F",
  "bitlinks": [
    {
      "campaign_guid": "Ca1bcd2EFGh",
      "bitlink_id": "bit.ly/1234abcd"
    }
  ]
}' \
https://api-ssl.bitly.com/v4/channels/Ha1bc2DefGh
{
  "name": "string",
  "guid": "string",
  "created": "string",
  "modified": "string",
  "group_guid": "string",
  "references": { "any" }
}

Custom Bitlinks

These endpoints are for updating custom Bitlinks only. Custom Bitlinks have both a BSD and a customized back-half (e.g., yourcompany.com/yourcampaign). If a link begins with the bit.ly domain or ends with an auto-generated random string it is not a custom Bitlink.

Add Custom Bitlink

Post
/v4/custom_bitlinks

Add a keyword (or "custom back-half") to a Bitlink with a Custom Domain (domains must match). This endpoint can also be used for initial redirects to a link.

Request Body Schema

custom_bitlinkstring
bitlink_idstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "custom_bitlink": "chauncey.ly/documentation",
  "bitlink_id": "chauncey.ly/1234abcd"
}' \
https://api-ssl.bitly.com/v4/custom_bitlinks
{
  "custom_bitlink": "string",
  "bitlink": {
    "references": { "any" },
    "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"
    ],
    "launchpad_ids": [
      "string"
    ],
    "qr_code_ids": [
      "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"
      }
    ],
    "campaign_ids": [
      "string"
    ]
  },
  "bitlink_history": [
    {
      "group_guid": "string",
      "keyword": "string",
      "bsd": "string",
      "hash": "string",
      "login": "string",
      "long_url": "string",
      "created": "string",
      "first_created": "string",
      "deactivated": "string",
      "is_active": "boolean"
    }
  ]
}

Update Custom Bitlink

Patch
/v4/custom_bitlinks/{custom_bitlink}

Move a keyword (or custom back-half) to a different Bitlink (domains must match).

Path Parameters

custom_bitlinkstringRequired
A Custom Bitlink made of the domain and keyword

Request Body Schema

bitlink_idstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "bitlink_id": "chauncey.ly/1234abcd"
}' \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chauncey
{
  "custom_bitlink": "string",
  "bitlink": {
    "references": { "any" },
    "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"
    ],
    "launchpad_ids": [
      "string"
    ],
    "qr_code_ids": [
      "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"
      }
    ],
    "campaign_ids": [
      "string"
    ]
  },
  "bitlink_history": [
    {
      "group_guid": "string",
      "keyword": "string",
      "bsd": "string",
      "hash": "string",
      "login": "string",
      "long_url": "string",
      "created": "string",
      "first_created": "string",
      "deactivated": "string",
      "is_active": "boolean"
    }
  ]
}

Retrieve Custom Bitlink

Get
/v4/custom_bitlinks/{custom_bitlink}

Returns the details and history of the specified link.

Path Parameters

custom_bitlinkstringRequired
A Custom Bitlink made of the domain and keyword
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chauncey
{
  "custom_bitlink": "string",
  "bitlink": {
    "references": { "any" },
    "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"
    ],
    "launchpad_ids": [
      "string"
    ],
    "qr_code_ids": [
      "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"
      }
    ],
    "campaign_ids": [
      "string"
    ]
  },
  "bitlink_history": [
    {
      "group_guid": "string",
      "keyword": "string",
      "bsd": "string",
      "hash": "string",
      "login": "string",
      "long_url": "string",
      "created": "string",
      "first_created": "string",
      "deactivated": "string",
      "is_active": "boolean"
    }
  ]
}

Get Metrics for a Custom Bitlink by Destination

Get
/v4/custom_bitlinks/{custom_bitlink}/clicks_by_destination

Returns click metrics for the specified link by its historical destinations.

Path Parameters

custom_bitlinkstringRequired
A Custom Bitlink made of the domain and keyword

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chauncey/clicks_by_destination?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Clicks for a Custom Bitlink's Entire History

Get
/v4/custom_bitlinks/{custom_bitlink}/clicks

Returns the click counts for the specified link. This returns an array with clicks based on a date.

Path Parameters

custom_bitlinkstringRequired
A Custom Bitlink made of the domain and keyword

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chauncey/clicks?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "link_clicks": [
    {
      "clicks": "integer",
      "date": "string"
    }
  ],
  "units": "integer",
  "unit": "string",
  "unit_reference": "string"
}

Groups

Groups are subdivisions within organizations. Every user will be in at least one group, and every shortened link will be in one group. Most actions on our API will be on behalf of a group. For example, when you shorten a link, it will be on behalf of a user and a group.

Retrieve Groups

Get
/v4/groups

Returns a list of groups in the organization.

Query Parameters

organization_guidstring
A GUID for a Bitly organization
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups?organization_guid=Oa1bcd234eF
{
  "groups": [
    {
      "references": { "any" },
      "name": "string",
      "guid": "string",
      "created": "string",
      "modified": "string",
      "is_active": "boolean",
      "role": "string",
      "organization_guid": "string",
      "bsds": [
        "string"
      ]
    }
  ]
}

Update a Group

Patch
/v4/groups/{group_guid}

Updates the details of a group.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Request Body Schema

namestring
organization_guidstring
bsdsarray of string
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "name": "My New Group",
  "organization_guid": "Oa1bcd234eF",
  "bsds": [
    "chauncey.ly"
  ]
}' \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F
{
  "references": { "any" },
  "name": "string",
  "guid": "string",
  "created": "string",
  "modified": "string",
  "is_active": "boolean",
  "role": "string",
  "organization_guid": "string",
  "bsds": [
    "string"
  ]
}

Retrieve a Group

Get
/v4/groups/{group_guid}

Returns details for a group.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F
{
  "references": { "any" },
  "name": "string",
  "guid": "string",
  "created": "string",
  "modified": "string",
  "is_active": "boolean",
  "role": "string",
  "organization_guid": "string",
  "bsds": [
    "string"
  ]
}

Retrieve Tags by Group

Get
/v4/groups/{group_guid}/tags

Returns the tags currently used in the specified group. Maximum 1000.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/tags
{
  "tags": [
    "string"
  ]
}

Retrieve Group Preferences

Get
/v4/groups/{group_guid}/preferences

Returns preferences for the specified group.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/preferences
{
  "group_guid": "string",
  "domain_preference": "string"
}

Update Group Preferences

Patch
/v4/groups/{group_guid}/preferences

Updates preferences for a group.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Request Body Schema

group_guidstring
domain_preferencestring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "group_guid": "Ba1bc23dE4F",
  "domain_preference": "chauncey.ly"
}' \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/preferences
{
  "group_guid": "string",
  "domain_preference": "string"
}

Retrieve Group Shorten Counts

Get
/v4/groups/{group_guid}/shorten_counts

Returns all the shorten counts for a group.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/shorten_counts?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "key": "string",
      "value": "integer"
    }
  ]
}

Get Click Metrics for a Group by Country

Get
/v4/groups/{group_guid}/countries

Returns the geographic origins of click traffic by country for the specified group.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/countries?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Click Metrics for a Group by City

Get
/v4/groups/{group_guid}/cities

Returns the geographic origins of click traffic by city for the specified group.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/cities?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "city": "string",
      "subregion": "string",
      "region": "string",
      "country": "string"
    }
  ],
  "other_metrics": {
    "other_city_clicks": "integer",
    "no_city_clicks": "integer"
  }
}

Get Click Metrics for a Group by Device Type

Get
/v4/groups/{group_guid}/devices

Returns the device types generating click traffic to the specified group's links.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/devices?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "device_type": "string"
    }
  ]
}

Get Click Metrics for a Group by Referring Networks

Get
/v4/groups/{group_guid}/referring_networks

Returns metrics by referring networks for the specified group's links.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/referring_networks?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Click Metrics for a Group by Referrer

Get
/v4/groups/{group_guid}/referrers

Returns metrics by referrer for the specified group's links.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/referrers?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get clicks by group

Get
/v4/groups/{group_guid}/clicks

get number of clicks on bitlinks in a group

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/clicks?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "unit_reference": "string",
  "data": [
    {
      "ts": "string",
      "count": "integer"
    }
  ]
}

Get limit usage for a group

Get
/v4/groups/{group_guid}/feature_usage

Get a group's current feature limit usage, optionally provide limit name(s) for usage on specific limit(s)

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

namearray
The limit name you would like usage for
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/feature_usage?name=qr_codes
{
  "group_guid": "string",
  "limit_usage": [
    {
      "name": "string",
      "description": "string",
      "count": "integer"
    }
  ]
}

Get historical usage for a group

Get
/v4/groups/{group_guid}/historical_usage

Get a group's historical usage for specific limit(s) and date range. Refer to GET /v4/groups/{group_guid}/feature_usage endpoint response for available limit names.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

namearray
The limit name you would like usage for
start_datestring
The start date for the date range
end_datestring
The end date for the date range
unitstring
A unit of time (day, week, or month)
Default: "month"
Enum: "day""week""month"
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/historical_usage?name=qr_codes&start_date=2022-02-02&end_date=2023-10-04&unit=month
{
  "group_guid": "string",
  "unit": "string",
  "start_date": "string",
  "end_date": "string",
  "historical_limit_usage": [
    {
      "name": "string",
      "usage": [
        {
          "count": "integer",
          "unit_start": "string"
        }
      ]
    }
  ]
}

Organizations

Organizations are equivalent to a Bitly account. Every plan limit, group, and user is tied to an organization.

Retrieve Organizations

Get
/v4/organizations

Retrieve a list of organizations.

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations
{
  "organizations": [
    {
      "references": { "any" },
      "name": "string",
      "is_active": "boolean",
      "guid": "string",
      "tier": "string",
      "tier_family": "string",
      "tier_display_name": "string",
      "role": "string",
      "created": "string",
      "modified": "string",
      "bsds": [
        "string"
      ]
    }
  ]
}

Retrieve an Organization

Get
/v4/organizations/{organization_guid}

Retrive details for the specified organization.

Path Parameters

organization_guidstringRequired
A GUID for a Bitly organization
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF
{
  "references": { "any" },
  "name": "string",
  "is_active": "boolean",
  "guid": "string",
  "tier": "string",
  "tier_family": "string",
  "tier_display_name": "string",
  "role": "string",
  "created": "string",
  "modified": "string",
  "bsds": [
    "string"
  ]
}

Get Shorten Counts for an Organization

Get
/v4/organizations/{organization_guid}/shorten_counts

Returns the shorten counts for a specific organization over a specified time period.

Path Parameters

organization_guidstringRequired
A GUID for a Bitly organization

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/shorten_counts?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "key": "string",
      "value": "integer"
    }
  ]
}

Get Shorten Counts for an Organization by Group

Get
/v4/organizations/{organization_guid}/shorten_counts_by_group

Returns the shorten counts for a specific organization by group for the current month.

Path Parameters

organization_guidstringRequired
A GUID for a Bitly organization
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/shorten_counts_by_group
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "key": "string",
      "value": "integer"
    }
  ]
}

Get Plan Limits

Get
/v4/organizations/{organization_guid}/plan_limits

Returns all plan limits and counts available for an organization.

Path Parameters

organization_guidstringRequired
A GUID for a Bitly organization
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/plan_limits
{
  "references": { "any" },
  "organization_guid": "string",
  "plan_limits": [
    {
      "name": "string",
      "description": "string",
      "limit": "integer",
      "count": "integer"
    }
  ]
}

QR Codes

QR codes can be created and customized with different dot patterns, corner shapes, colors, and more. They can contain bitlinks, links to microsites, or several kinds of static data.

Create a QR Code

Post
/v4/qr-codes

Create a new QR Code and return its metadata

Request Body Schema

titlestring
The title of the QR Code
group_guidstringRequired
Identify which group to place the QR Code.
render_customizationsobject
Options for customizing a QR Code's appearance
background_colorstring
The QR code's background color in hex code format with values for alpha channel
dot_pattern_colorstring
The QR code's dot pattern color in hex code format
dot_pattern_typestring
Default: "standard"
Enum: "standard""circle""block""blob""rounded""vertical""horizontal""triangle""heart""star""diamond"
cornersobject
An object representing all three corners of the QR code. The corners corresponding to each property are: corner_1 = top left, corner_2 = top right, and corner_3 = bottom right
corner_1object
Represents one corner, both inner and outer, of a QR code, with color and shape values
inner_colorstring
The inner color of a corner of the QR code in hex code format
outer_colorstring
The outer color of a corner of the QR code in hex code format
shapestring
The shape one of the QR code's corners should take
Default: "standard"
Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"
corner_2object
Represents one corner, both inner and outer, of a QR code, with color and shape values
inner_colorstring
The inner color of a corner of the QR code in hex code format
outer_colorstring
The outer color of a corner of the QR code in hex code format
shapestring
The shape one of the QR code's corners should take
Default: "standard"
Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"
corner_3object
Represents one corner, both inner and outer, of a QR code, with color and shape values
inner_colorstring
The inner color of a corner of the QR code in hex code format
outer_colorstring
The outer color of a corner of the QR code in hex code format
shapestring
The shape one of the QR code's corners should take
Default: "standard"
Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"
gradientobject
stylestring
The style of the gradient. Can be either linear or radial.
Default: "no_gradient"
Enum: "no_gradient""linear""radial"
anglenumber
The angle by which the gradient will be rotated. Only applies to linear gradients.
colorsarray
The list of hex colors and their offsets to be used in the gradient.
exclude_cornersboolean
Ignore gradient mask on corners
background_gradientobject
stylestring
The style of the gradient. Can be either linear or radial.
Default: "no_gradient"
Enum: "no_gradient""linear""radial"
anglenumber
The angle by which the gradient will be rotated. Only applies to linear gradients.
colorsarray
The list of hex colors and their offsets to be used in the gradient.
exclude_cornersboolean
Ignore gradient mask on corners
logoobject
image_guidstring
A GUID for an image uploaded to Bitly
frameobject
idstring
The unique id of the selected frame
Default: "none"
Enum: "none""border_only""text_bottom""tooltip_bottom""arrow""text_top""text_bottom_in_frame""script""text_top_and_bottom""url""instagram"
colorsobject
An object of named colors denoting which color should go to which area of the frame
primarystring
The primary color of the frame in hex code format
secondarystring
The secondary color of the frame in hex code format
backgroundstring
The background color of the frame in hex code format
textobject
The text to be inserted into the QR code's frame
primaryobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
secondaryobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
textobject
Contains the center, top, and bottom text to be used in the QR code
centerobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
topobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
bottomobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
brandingobject
bitly_brandboolean
A boolean that determines if the QR code should have the bitly brand in its bottom right corner
spec_settingsobject
The QR code's editable spec settings, which for now is just the error correction
error_correctioninteger
The amount of error correction that the QR code was generated with
archivedboolean
A boolean representing if the QR code should be archived (hidden from the UI) upon creation
destinationobjectRequired
bitlink_idstring
long_urlstring
site_idstring
gs1object
Contains GS1 related metadata
valuesarray
A list of GS1 application identifiers and their values
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "title": "Default QR Code",
  "group_guid": "Ba1bc23dE4F",
  "destination": {
    "bitlink_id": "bit.ly/abc123"
  },
  "archived": false,
  "render_customizations": {
    "background_color": "#ffffff",
    "dot_pattern_color": "#000000",
    "dot_pattern_type": "standard",
    "corners": {
      "corner_1": {
        "inner_color": "#000000",
        "outer_color": "#000000",
        "shape": "standard"
      },
      "corner_2": {
        "inner_color": "#000000",
        "outer_color": "#000000",
        "shape": "standard"
      },
      "corner_3": {
        "inner_color": "#000000",
        "outer_color": "#000000",
        "shape": "standard"
      }
    },
    "branding": {
      "bitly_brand": true
    },
    "spec_settings": {
      "error_correction": 4
    }
  }
}' \
https://api-ssl.bitly.com/v4/qr-codes
{
  "qrcode_id": "string",
  "group_guid": "string",
  "title": "string",
  "is_customized": "boolean",
  "serialized_content": "string",
  "qr_code_type": "string",
  "long_urls": [
    "string"
  ],
  "bitlink_id": "string",
  "is_gs1": "boolean",
  "created_by": "string",
  "archived": "boolean",
  "created": "string",
  "modified": "string"
}

Retrieve a QR Code image

Get
/v4/qr-codes/{qrcode_id}/image

Get the image of a given QR Code. The Accept header controls how this is returned (options are "application/json", "image/svg+xml", and "image/png"). If the Accept header is "application/json" the format query parameter will determine the image format inside of the json (which will be base64 encoded and prefixed with its mime type as would be suitable for a HTML image src tag). To Return the QR Code image itself, set the Accept header to "image/svg+xml" or "image/png", or remove the Accept header and set the format query parameter to “svg” or “png” (if no format is specified the default will be “svg”).

Header Parameters

Acceptstring
The file format for the QR code's image. If the accept header is application/json the image data will be wrapped in a json object, base64 encoded and prefixed with its mime type as would be suitable for a HTML image src tag.

Path Parameters

qrcode_idstringRequired
The QR Code ID

Query Parameters

formatstring
The format type of the image. If there is an image format in the header it takes precedence.
Default: "svg"
Enum: "svg""png"
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Accept: image/svg+xml' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/image?format=
{
  "qr_code_image": "string"
}

Update a QR Code

Patch
/v4/qr-codes/{qrcode_id}

Updates the QR code with a matching id and returns it.

Path Parameters

qrcode_idstringRequired
The QR code ID

Request Body Schema

titlestring
render_customizationsobject
Options for customizing a QR Code's appearance
background_colorstring
The QR code's background color in hex code format with values for alpha channel
dot_pattern_colorstring
The QR code's dot pattern color in hex code format
dot_pattern_typestring
Default: "standard"
Enum: "standard""circle""block""blob""rounded""vertical""horizontal""triangle""heart""star""diamond"
cornersobject
An object representing all three corners of the QR code. The corners corresponding to each property are: corner_1 = top left, corner_2 = top right, and corner_3 = bottom right
corner_1object
Represents one corner, both inner and outer, of a QR code, with color and shape values
inner_colorstring
The inner color of a corner of the QR code in hex code format
outer_colorstring
The outer color of a corner of the QR code in hex code format
shapestring
The shape one of the QR code's corners should take
Default: "standard"
Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"
corner_2object
Represents one corner, both inner and outer, of a QR code, with color and shape values
inner_colorstring
The inner color of a corner of the QR code in hex code format
outer_colorstring
The outer color of a corner of the QR code in hex code format
shapestring
The shape one of the QR code's corners should take
Default: "standard"
Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"
corner_3object
Represents one corner, both inner and outer, of a QR code, with color and shape values
inner_colorstring
The inner color of a corner of the QR code in hex code format
outer_colorstring
The outer color of a corner of the QR code in hex code format
shapestring
The shape one of the QR code's corners should take
Default: "standard"
Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"
gradientobject
stylestring
The style of the gradient. Can be either linear or radial.
Default: "no_gradient"
Enum: "no_gradient""linear""radial"
anglenumber
The angle by which the gradient will be rotated. Only applies to linear gradients.
colorsarray
The list of hex colors and their offsets to be used in the gradient.
exclude_cornersboolean
Ignore gradient mask on corners
background_gradientobject
stylestring
The style of the gradient. Can be either linear or radial.
Default: "no_gradient"
Enum: "no_gradient""linear""radial"
anglenumber
The angle by which the gradient will be rotated. Only applies to linear gradients.
colorsarray
The list of hex colors and their offsets to be used in the gradient.
exclude_cornersboolean
Ignore gradient mask on corners
logoobject
image_guidstring
A GUID for an image uploaded to Bitly
frameobject
idstring
The unique id of the selected frame
Default: "none"
Enum: "none""border_only""text_bottom""tooltip_bottom""arrow""text_top""text_bottom_in_frame""script""text_top_and_bottom""url""instagram"
colorsobject
An object of named colors denoting which color should go to which area of the frame
primarystring
The primary color of the frame in hex code format
secondarystring
The secondary color of the frame in hex code format
backgroundstring
The background color of the frame in hex code format
textobject
The text to be inserted into the QR code's frame
primaryobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
secondaryobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
textobject
Contains the center, top, and bottom text to be used in the QR code
centerobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
topobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
bottomobject
An object describing text with color
contentstring
The text to be used
colorstring
The color of the text in hex code format
Default: "#ffffff"
brandingobject
bitly_brandboolean
A boolean that determines if the QR code should have the bitly brand in its bottom right corner
spec_settingsobject
The QR code's editable spec settings, which for now is just the error correction
error_correctioninteger
The amount of error correction that the QR code was generated with
archivedboolean
A boolean representing if the QR code has been archived
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "title": "Default QR Code Updated",
  "archived": false,
  "render_customizations": {
    "background_color": "#ffffff",
    "dot_pattern_color": "#000000",
    "dot_pattern_type": "standard",
    "corners": {
      "corner_1": {
        "inner_color": "#000000",
        "outer_color": "#000000",
        "shape": "standard"
      },
      "corner_2": {
        "inner_color": "#000000",
        "outer_color": "#000000",
        "shape": "standard"
      },
      "corner_3": {
        "inner_color": "#000000",
        "outer_color": "#000000",
        "shape": "standard"
      }
    },
    "branding": {
      "bitly_brand": true
    },
    "spec_settings": {
      "error_correction": 4
    }
  }
}' \
https://api-ssl.bitly.com/v4/qr-codes/Qabc123
{
  "qrcode_id": "string",
  "group_guid": "string",
  "title": "string",
  "is_customized": "boolean",
  "serialized_content": "string",
  "qr_code_type": "string",
  "long_urls": [
    "string"
  ],
  "bitlink_id": "string",
  "is_gs1": "boolean",
  "created_by": "string",
  "archived": "boolean",
  "created": "string",
  "modified": "string"
}

Retrieve a QR Code

Get
/v4/qr-codes/{qrcode_id}

Gets the QR code with a matching id.

Path Parameters

qrcode_idstringRequired
The QR Code ID
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345
{
  "qrcode_id": "string",
  "group_guid": "string",
  "title": "string",
  "gs1": {
    "values": [
      {
        "key": "string",
        "value": "string"
      }
    ]
  },
  "render_customizations": {
    "background_color": "string",
    "dot_pattern_color": "string",
    "dot_pattern_type": "string",
    "corners": {
      "corner_1": {
        "inner_color": "string",
        "outer_color": "string",
        "shape": "string"
      },
      "corner_2": {
        "inner_color": "string",
        "outer_color": "string",
        "shape": "string"
      },
      "corner_3": {
        "inner_color": "string",
        "outer_color": "string",
        "shape": "string"
      }
    },
    "gradient": {
      "style": "string",
      "angle": "number",
      "colors": [
        {
          "color": "string",
          "offset": "integer"
        }
      ],
      "exclude_corners": "boolean"
    },
    "background_gradient": {
      "style": "string",
      "angle": "number",
      "colors": [
        {
          "color": "string",
          "offset": "integer"
        }
      ],
      "exclude_corners": "boolean"
    },
    "logo": {
      "image_guid": "string"
    },
    "frame": {
      "id": "string",
      "colors": {
        "primary": "string",
        "secondary": "string",
        "background": "string"
      },
      "text": {
        "primary": {
          "content": "string",
          "color": "string"
        },
        "secondary": {
          "content": "string",
          "color": "string"
        }
      }
    },
    "text": {
      "center": {
        "content": "string",
        "color": "string"
      },
      "top": {
        "content": "string",
        "color": "string"
      },
      "bottom": {
        "content": "string",
        "color": "string"
      }
    },
    "branding": {
      "bitly_brand": "boolean"
    },
    "spec_settings": {
      "error_correction": "integer"
    }
  },
  "qr_code_type": "string",
  "bitlink_id": "string",
  "long_urls": [
    "string"
  ],
  "serialized_content": "string",
  "archived": "boolean",
  "created": "string",
  "modified": "string"
}

Delete a QR Code

Delete
/v4/qr-codes/{qrcode_id}

Delete a QR Code that has not been redirected and is not for a custom link. Also deletes the associated link (if applicable).

Path Parameters

qrcode_idstringRequired
The QR Code ID
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X DELETE \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345
{
  "qrcodes_deleted": [
    {
      "id": "string"
    }
  ],
  "links_deleted": [
    {
      "id": "string"
    }
  ]
}

Retrieve QR Codes by Group

Get
/v4/groups/{group_guid}/qr-codes

Retrieves a list of QR codes matching the filter settings. Values are in reverse chronological order. The pagination occurs by calling the next link in the pagination response object.

Path Parameters

group_guidstringRequired
A GUID for a Bitly group

Query Parameters

has_render_customizationsstring
Whether or not QRCode has any render customizations (like color or shape changes)
Default: "both"
Enum: "on""off""both"
sizeinteger
The quantity of items to be be returned
Default: 50
search_afterstring
Token used to search next batch of qr codes, only use response from API as input value.
querystring
The value that you would like to search
created_beforeinteger
Timestamp as an integer unix epoch (seconds only)
created_afterinteger
Timestamp as an integer unix epoch (seconds only)
archivedstring
Whether or not to include archived resources
Default: "off"
Enum: "on""off""both"
creating_loginarray
Filter by the login of the authenticated user that created the QR Code
qrc_typearray
Default: ["bitlink", "long_url"]
is_gs1string
a filter value if the resource is a GS1 QR code
Default: "both"
Enum: "on""off""both"
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/qr-codes?has_render_customizations=both&size=10&search_after=&query=api&created_before=1694529902&created_after=1694529902&archived=both&creating_login=chauncey&qrc_type=&is_gs1=both
{
  "qr_codes": [
    {
      "qrcode_id": "string",
      "group_guid": "string",
      "title": "string",
      "is_customized": "boolean",
      "serialized_content": "string",
      "qr_code_type": "string",
      "long_urls": [
        "string"
      ],
      "bitlink_id": "string",
      "is_gs1": "boolean",
      "created_by": "string",
      "archived": "boolean",
      "created": "string",
      "modified": "string"
    }
  ],
  "pagination": {
    "next": "string",
    "search_after": "string",
    "size": "integer"
  }
}

Get Scans for a QR Code

Get
/v4/qr-codes/{qrcode_id}/scans

Returns an array of scan counts for the specified QR code. The array is comprised of scan counts for each time window, where the window is based on the provided unit.

Path Parameters

qrcode_idstringRequired
The QR Code ID

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "scans": [
    {
      "scans": "integer",
      "date": "string"
    }
  ],
  "units": "integer",
  "unit": "string",
  "unit_reference": "string"
}

Get Scans Summary for a QR Code

Get
/v4/qr-codes/{qrcode_id}/scans/summary

Returns the scan counts for a QR Code rolled up into a single field for a specified time window, where the window is based on the provided unit.

Path Parameters

qrcode_idstringRequired
The QR Code ID

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/summary?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "total_scans": "integer",
  "units": "integer",
  "unit": "string",
  "unit_reference": "string"
}

Get Scans for a QR Code by Country

Get
/v4/qr-codes/{qrcode_id}/scans/countries

Returns the country origins of scan traffic for the specified QR Code.

Path Parameters

qrcode_idstringRequired
The QR Code ID

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/countries?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "scans": "integer",
      "value": "string"
    }
  ]
}

Get Metrics for a QR Code by City

Get
/v4/qr-codes/{qrcode_id}/scans/cities

Returns the city origins of scan traffic for the specified QR Code.

Path Parameters

qrcode_idstringRequired
The QR Code ID

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/cities?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "scans": "integer",
      "city": "string",
      "subregion": "string",
      "region": "string",
      "country": "string"
    }
  ],
  "other_metrics": {
    "other_city_scans": "integer",
    "no_city_scans": "integer"
  }
}

Get Scans for a QR Code by Device OS

Get
/v4/qr-codes/{qrcode_id}/scans/device_os

Returns the device os generating scan traffic for the specified QR Code.

Path Parameters

qrcode_idstringRequired
The QR Code ID

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/device_os?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "scans": "integer",
      "value": "string"
    }
  ]
}

Get Scans for a QR Code by Browser

Get
/v4/qr-codes/{qrcode_id}/scans/browsers

Returns the browsers generating scan traffic to the specified QR Code.

Path Parameters

qrcode_idstringRequired
The QR Code ID

Query Parameters

unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time. Timestamp values should be url encoded (i.e. replace '+' with '%2B' and ':' with '%3A'; 2022-02-02T15:53:02+0000 becomes 2022-02-02T15%3A53%3A02%2B0000)
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/browsers?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "scans": "integer",
      "value": "string"
    }
  ]
}

User

Some subscription plans allow multiple users. Only one user is used for authenticating a call, and these operations apply only to the authenticated user.

Update a User

Patch
/v4/user

Update fields in the user

Request Body Schema

namestring
default_group_guidstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "name": "Chauncey McPufferson",
  "default_group_guid": "Ba1bc23dE4F"
}' \
https://api-ssl.bitly.com/v4/user
{
  "login": "string",
  "name": "string",
  "is_active": "boolean",
  "created": "string",
  "modified": "string",
  "is_sso_user": "boolean",
  "emails": [
    {
      "email": "string",
      "is_primary": "boolean",
      "is_verified": "boolean"
    }
  ],
  "is_2fa_enabled": "boolean",
  "default_group_guid": "string"
}

Retrieve a User

Get
/v4/user

Returns information for the current authenticated user.

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/user
{
  "login": "string",
  "name": "string",
  "is_active": "boolean",
  "created": "string",
  "modified": "string",
  "is_sso_user": "boolean",
  "emails": [
    {
      "email": "string",
      "is_primary": "boolean",
      "is_verified": "boolean"
    }
  ],
  "is_2fa_enabled": "boolean",
  "default_group_guid": "string"
}

Get Platform Limits

Get
/v4/user/platform_limits

Fetch all platform limits and counts available for an organization

Query Parameters

pathstring
The specific path for which information is requested
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/user/platform_limits?path=%2Forganizations%2F%7Borganization_guid%7D
{
  "platform_limits": [
    {
      "endpoint": "string",
      "methods": [
        {
          "name": "string",
          "limit": "integer",
          "count": "integer"
        }
      ]
    }
  ]
}

Webhooks

Webhooks are a method of sending information from Bitly to an application outside of Bitly. It's a way to automate actions or updates between two different systems. These endpoints are for configuring your webhooks.

Get Webhooks

Get
/v4/organizations/{organization_guid}/webhooks

Fetch all webhooks available for an Organization

Path Parameters

organization_guidstringRequired
A GUID for a Bitly organization
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/webhooks
{
  "webhooks": [
    {
      "references": { "any" },
      "guid": "string",
      "created": "string",
      "modified": "string",
      "modified_by": "string",
      "alerted": "string",
      "deactivated": "string",
      "is_active": "boolean",
      "is_alert": "boolean",
      "organization_guid": "string",
      "group_guid": "string",
      "name": "string",
      "event": "string",
      "url": "string",
      "status": "string",
      "oauth_url": "string",
      "client_id": "string",
      "client_secret": "string",
      "fetch_tags": "boolean"
    }
  ]
}

Create Webhook

Post
/v4/webhooks

Creates a webhook.

Request Body Schema

is_activeboolean
organization_guidstringRequired
group_guidstring
namestringRequired
eventstringRequired
urlstringRequired
oauth_urlstring
client_idstring
client_secretstring
fetch_tagsboolean
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "is_active": true,
  "organization_guid": "Oa1bcd234eF",
  "group_guid": "Ba1bc23dE4F",
  "name": "My Webhook",
  "event": "decodes",
  "url": "https://bitly.com/webhooks",
  "oauth_url": "https://fake.com/oauth",
  "client_id": "fakeclientid123",
  "client_secret": "itsasecreticanttellyou"
}' \
https://api-ssl.bitly.com/v4/webhooks
{
  "references": { "any" },
  "guid": "string",
  "created": "string",
  "modified": "string",
  "modified_by": "string",
  "alerted": "string",
  "deactivated": "string",
  "is_active": "boolean",
  "is_alert": "boolean",
  "organization_guid": "string",
  "group_guid": "string",
  "name": "string",
  "event": "string",
  "url": "string",
  "status": "string",
  "oauth_url": "string",
  "client_id": "string",
  "client_secret": "string",
  "fetch_tags": "boolean"
}

Retrieve Webhook

Get
/v4/webhooks/{webhook_guid}

Returns a webhook.

Path Parameters

webhook_guidstringRequired
A GUID for a Bitly webhook
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/webhooks/Wa1bcDefG23
{
  "references": { "any" },
  "guid": "string",
  "created": "string",
  "modified": "string",
  "modified_by": "string",
  "alerted": "string",
  "deactivated": "string",
  "is_active": "boolean",
  "is_alert": "boolean",
  "organization_guid": "string",
  "group_guid": "string",
  "name": "string",
  "event": "string",
  "url": "string",
  "status": "string",
  "oauth_url": "string",
  "client_id": "string",
  "client_secret": "string",
  "fetch_tags": "boolean"
}

Update Webhook

Patch
/v4/webhooks/{webhook_guid}

Update a webhook

Path Parameters

webhook_guidstringRequired
A GUID for a Bitly webhook

Request Body Schema

guidstringRequired
is_activeboolean
organization_guidstring
group_guidstring
namestring
eventstring
urlstring
oauth_urlstring
client_idstring
client_secretstring
fetch_tagsboolean
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "guid": "Wa1bcDefG23",
  "is_active": true,
  "organization_guid": "Oa1bcd234eF",
  "group_guid": "Ba1bc23dE4F",
  "name": "My Webhook",
  "event": "decodes",
  "url": "https://bitly.com/webhooks",
  "oauth_url": "https://fake.com/oauth",
  "client_id": "fakeclientid123",
  "client_secret": "itsasecreticanttellyou"
}' \
https://api-ssl.bitly.com/v4/webhooks/Wa1bcDefG23
{
  "references": { "any" },
  "guid": "string",
  "created": "string",
  "modified": "string",
  "modified_by": "string",
  "alerted": "string",
  "deactivated": "string",
  "is_active": "boolean",
  "is_alert": "boolean",
  "organization_guid": "string",
  "group_guid": "string",
  "name": "string",
  "event": "string",
  "url": "string",
  "status": "string",
  "oauth_url": "string",
  "client_id": "string",
  "client_secret": "string",
  "fetch_tags": "boolean"
}

Delete Webhook

Delete
/v4/webhooks/{webhook_guid}

Deletes a webhook.

Path Parameters

webhook_guidstringRequired
A GUID for a Bitly webhook
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X DELETE \
https://api-ssl.bitly.com/v4/webhooks/Wa1bcDefG23

Verify Webhook

Post
/v4/webhooks/{webhook_guid}/verify

Sends ping event to test webhook configuration.

Path Parameters

webhook_guidstringRequired
A GUID for a Bitly webhook
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X POST \
https://api-ssl.bitly.com/v4/webhooks/Wa1bcDefG23/verify
{
  "references": { "any" },
  "guid": "string",
  "created": "string",
  "modified": "string",
  "modified_by": "string",
  "alerted": "string",
  "deactivated": "string",
  "is_active": "boolean",
  "is_alert": "boolean",
  "organization_guid": "string",
  "group_guid": "string",
  "name": "string",
  "event": "string",
  "url": "string",
  "status": "string",
  "oauth_url": "string",
  "client_id": "string",
  "client_secret": "string",
  "fetch_tags": "boolean"
}