BITLY API REFERENCE
BITLY API REFERENCE
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
/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.
Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X DELETE \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"links_deleted": [
{
"id": "string"
}
]
}
Update a Bitlink
/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
Request
cURLNodeBrowserGoPython
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&h
l=en_US",
"app_guid": "Ab1cdE2fG3h",
"os": "android",
"install_type": "promote_install",
"brand_guid": "Ba1bc23dE4F"
}
]
}' \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE422 UNPROCESSABLE_ENTITY429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/v4/bitlinks/{bitlink}
Returns information for the specified link.
Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND410 GONE429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/v4/expand
Returns the short link and long URL 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
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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/clicks?un
it=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"link_clicks": [
{
"clicks": "integer",
"date": "string"
}
],
"units": "integer",
"unit": "string",
"unit_reference": "string"
}
Get a Clicks Summary for a Bitlink
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/clicks/su
mmary?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A0
5-0700
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"total_clicks": "integer",
"units": "integer",
"unit": "string",
"unit_reference": "string"
}
Get Metrics for a Bitlink by Country
/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)
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE429 MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"value": "string"
}
]
}
Get Metrics for a Bitlink by City
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/cities?un
it=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A0
5-0700
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
json
csv
{
"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
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/devices?u
nit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A
05-0700
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
json
csv
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"device_type": "string"
}
]
}
Get Metrics for a Bitlink by Referrers
/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)
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE429 MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"value": "string"
}
]
}
Get Metrics for a Bitlink by Referrer Name
/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)
Request
cURLNodeBrowserGoPython
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%3
A04%3A05-0700
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE500 INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
json
csv
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"value": "string"
}
]
}
Get Metrics for a Bitlink by Referring Domains
/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)
Request
cURLNodeBrowserGoPython
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-02T
15%3A04%3A05-0700
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE429 MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"value": "string"
}
]
}
Get Metrics for a Bitlink by Referrers by Domain
/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)
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE429 MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"referrers_by_domain": [
{
"network": "string",
"referrers": [
{
"key": "string",
"value": "integer"
}
]
}
]
}
Retrieve Bitlinks by Group
/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 bitlinks
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
Request
cURLNodeBrowserGoPython
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_a
fter=1694529902&archived=both&deeplinks=both&domain_deeplinks=
both&campaign_guid=Ca1bcd2EFGh&channel_guid=Ha1bc2DefGh&custom
_bitlink=both&has_qr_codes=both&tags%5B0%5D=bitly&tags%5B1%5D=
api&launchpad_ids%5B0%5D=M1234567890&encoding_login%5B0%5D=cha
uncey
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/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
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND422
UNPROCESSABLE_ENTITY500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"links": [
"string"
]
}
Retrieve Sorted Bitlinks for Group
/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
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/bitlinks/click
s?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-07
00&size=10
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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"
}
]
}
Retrieve a QR Code
/v4/bitlinks/{bitlink}/qr
Retrieves a QR code for a Bitlink.
Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Query Parameters
image_formatstring
Determines the image format of the returned QR code
Default: "png"
Enum: "png""svg"
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/qr?image_
format=svg
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR
{
"id": "string",
"link": "string",
"group_guid": "string",
"customization": {
"color": "string",
"exclude_bitly_logo": "boolean",
"image_format": "string",
"logo_image_guid": "string",
"is_hidden": "boolean"
},
"qr_code": "string",
"logo_image_url": "string",
"is_customized": "boolean",
"is_hidden": "boolean",
"has_stored": "boolean",
"created": "string",
"modified": "string"
}
Update a QR Code
/v4/bitlinks/{bitlink}/qr
Updates an existing QR Code
Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Request Body Schema
colorstring
A color denoted in hexadecimal format ei. "1133ff"
exclude_bitly_logoboolean
Removes the Bitly logo from the center of the generated QR image
image_formatstring
Determines the image format of the returned QR code
Default: "png"
Enum: "png""svg"
logo_image_guidstring
Logo must first be uploaded through Bitly's QR Code Modal located on the "All links"
page. Once created, a call to "Retrieve a QR Code" with specified bitlink will return
the auto-generated "logo_image_guid"
is_hiddenboolean
Determine whether to hide the QR code. Passing true will hide the QR code.
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"color": "1133ff",
"exclude_bitly_logo": true,
"image_format": "svg",
"logo_image_guid": "I123456789",
"is_hidden": true
}' \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/qr
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR
{
"id": "string",
"link": "string",
"group_guid": "string",
"customization": {
"color": "string",
"exclude_bitly_logo": "boolean",
"image_format": "string",
"logo_image_guid": "string",
"is_hidden": "boolean"
},
"qr_code": "string",
"logo_image_url": "string",
"is_customized": "boolean",
"is_hidden": "boolean",
"has_stored": "boolean",
"created": "string",
"modified": "string"
}
Create a QR Code
/v4/bitlinks/{bitlink}/qr
Creates a QR code for existing Bitlink
Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Request Body Schema
colorstring
A color denoted in hexadecimal format ei. "1133ff"
exclude_bitly_logoboolean
Removes the Bitly logo from the center of the generated QR image
image_formatstring
Determines the image format of the returned QR code
Default: "png"
Enum: "png""svg"
logo_image_guidstring
Logo must first be uploaded through Bitly's QR Code Modal located on the "All links"
page. Once created, a call to "Retrieve a QR Code" with specified bitlink will return
the auto-generated "logo_image_guid"
is_hiddenboolean
Determine whether to hide the QR code. Passing true will hide the QR code.
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"color": "1133ff",
"exclude_bitly_logo": true,
"image_format": "svg",
"logo_image_guid": "I123456789",
"is_hidden": true
}' \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/qr
Response
201 CREATED400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR
{
"id": "string",
"link": "string",
"group_guid": "string",
"customization": {
"color": "string",
"exclude_bitly_logo": "boolean",
"image_format": "string",
"logo_image_guid": "string",
"is_hidden": "boolean"
},
"qr_code": "string",
"logo_image_url": "string",
"is_customized": "boolean",
"is_hidden": "boolean",
"has_stored": "boolean",
"created": "string",
"modified": "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
/v4/bsds
Fetch all Branded Short Domains
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bsds
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"bsds": [
"string"
]
}
Campaigns
Bitly Campaigns are used to build and organize links and metrics for marketing
campaigns.
Retrieve Campaigns
/v4/campaigns
Returns the campaigns for the current authenticated user.
Query Parameters
group_guidstring
A GUID for a Bitly group
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/campaigns?group_guid=Ba1bc23dE4F
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR502 BAD_GATEWAY503
TEMPORARILY_UNAVAILABLE
{
"campaigns": [
{
"references": { "any" },
"guid": "string",
"group_guid": "string",
"created_by": "string",
"name": "string",
"description": "string",
"created": "string",
"modified": "string"
}
]
}
Create Campaign
/v4/campaigns
Creates a new campaign.
Path Parameters
campaign_guidstringRequired
A GUID for a Bitly campaign
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/campaigns/Ca1bcd2EFGh
Response
200 SUCCESS402 UPGRADE_REQUIRED403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"references": { "any" },
"guid": "string",
"group_guid": "string",
"created_by": "string",
"name": "string",
"description": "string",
"created": "string",
"modified": "string"
}
Update Campaign
/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
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND422 UNPROCESSABLE_ENTITY429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"references": { "any" },
"guid": "string",
"group_guid": "string",
"created_by": "string",
"name": "string",
"description": "string",
"created": "string",
"modified": "string"
}
Retrieve Channels
/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
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/channels?group_guid=Ba1bc23dE4F&c
ampaign_guid=Ca1bcd2EFGh
Response
200 SUCCESS402 UPGRADE_REQUIRED403 FORBIDDEN404 NOT_FOUND500
INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
{
"channels": [
{
"name": "string",
"guid": "string",
"created": "string",
"modified": "string",
"group_guid": "string",
"references": { "any" }
}
]
}
Create Channel
/v4/channels
Creates a new channel.
Path Parameters
channel_guidstringRequired
A GUID for a Bitly Channel
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/channels/Ha1bc2DefGh
Response
200 SUCCESS402 UPGRADE_REQUIRED403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"name": "string",
"guid": "string",
"created": "string",
"modified": "string",
"group_guid": "string",
"references": { "any" }
}
Update a Channel
/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
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND422 UNPROCESSABLE_ENTITY429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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.
Path Parameters
custom_bitlinkstringRequired
A Custom Bitlink made of the domain and keyword
Request Body Schema
bitlink_idstring
Request
cURLNodeBrowserGoPython
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/chaun
cey
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND422 UNPROCESSABLE_ENTITY429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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": [
{
"uuid": "string",
"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
/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
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chaun
cey
Response
200 SUCCESS402 UPGRADE_REQUIRED403 FORBIDDEN404 NOT_FOUND410
GONE429 MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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": [
{
"uuid": "string",
"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
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chaun
cey/clicks_by_destination?unit=month&units=1&unit_reference=20
06-01-02T15%3A04%3A05-0700
Response
200 SUCCESS402 UPGRADE_REQUIRED403 FORBIDDEN404 NOT_FOUND410
GONE429 MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"value": "string"
}
]
}
Get Clicks for a Custom Bitlink's Entire History
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chaun
cey/clicks?unit=month&units=1&unit_reference=2006-01-02T15%3A0
4%3A05-0700
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
{
"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
/v4/groups
Returns a list of groups in the organization.
Query Parameters
organization_guidstring
A GUID for a Bitly organization
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups?organization_guid=Oa1bcd23
4eF
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND422
UNPROCESSABLE_ENTITY429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
{
"groups": [
{
"references": { "any" },
"name": "string",
"guid": "string",
"created": "string",
"modified": "string",
"is_active": "boolean",
"role": "string",
"organization_guid": "string",
"bsds": [
"string"
]
}
]
}
Update a Group
/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
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND422
UNPROCESSABLE_ENTITY500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"references": { "any" },
"name": "string",
"guid": "string",
"created": "string",
"modified": "string",
"is_active": "boolean",
"role": "string",
"organization_guid": "string",
"bsds": [
"string"
]
}
Retrieve a Group
/v4/groups/{group_guid}
Returns details for a group.
Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"references": { "any" },
"name": "string",
"guid": "string",
"created": "string",
"modified": "string",
"is_active": "boolean",
"role": "string",
"organization_guid": "string",
"bsds": [
"string"
]
}
Retrieve Tags by Group
/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
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/tags
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"tags": [
"string"
]
}
Retrieve Group Preferences
/v4/groups/{group_guid}/preferences
Returns preferences for the specified group.
Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/preferences
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"group_guid": "string",
"domain_preference": "string"
}
Update Group Preferences
/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
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND422
UNPROCESSABLE_ENTITY429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
{
"group_guid": "string",
"domain_preference": "string"
}
Retrieve Group Shorten Counts
/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)
Request
cURLNodeBrowserGoPython
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-070
0
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"key": "string",
"value": "integer"
}
]
}
Get Click Metrics for a Group by Country
/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)
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"value": "string"
}
]
}
Get Click Metrics for a Group by City
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/cities?unit=mo
nth&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-070
0
Response
200 SUCCESS402 UPGRADE_REQUIRED403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"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
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/devices?unit=m
onth&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-07
00
Response
200 SUCCESS402 UPGRADE_REQUIRED403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"device_type": "string"
}
]
}
Get Click Metrics for a Group by Referring Networks
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/referring_netw
orks?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3
A04%3A05-0700
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"value": "string"
}
]
}
Get Click Metrics for a Group by Referrer
/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)
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"clicks": "integer",
"value": "string"
}
]
}
Get clicks by group
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/clicks?unit=mo
nth&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN429 MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"unit": "string",
"units": "integer",
"unit_reference": "string",
"data": [
{
"ts": "string",
"count": "integer"
}
]
}
Retrieve QR Code Logo Images
/v4/groups/{group_guid}/qr/images
Retrieves logo images associated with QR codes by group
Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/qr/images
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN500 INTERNAL_ERROR
{
"qr_logo_images": [
{
"image_guid": "string",
"url": "string"
}
]
}
Organizations
Organizations are equivalent to a Bitly account. Every plan limit, group, and user is
tied to an organization.
Retrieve Organizations
/v4/organizations
Retrieve a list of organizations.
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/v4/organizations/{organization_guid}
Retrive details for the specified organization.
Path Parameters
organization_guidstringRequired
A GUID for a Bitly organization
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/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)
Request
cURLNodeBrowserGoPython
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%3
A05-0700
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"key": "string",
"value": "integer"
}
]
}
Get Shorten Counts for an Organization by Group
/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
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/shorten
_counts_by_group
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"key": "string",
"value": "integer"
}
]
}
Get Plan Limits
/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
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/plan_li
mits
Response
200 SUCCESS403 FORBIDDEN500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/v4/qr-codes
Create a new QR Code and return its metadata
Path Parameters
qrcode_idstringRequired
The QR Code ID
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/image
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE500 INTERNAL_ERROR
{
"qr_code_image": "string"
}
Update a QR Code
/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""di
amond"
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_fr
ame""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"
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
Request
DefaultMinimalComplexGradientsFramedLowest Error Correction
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE500 INTERNAL_ERROR
{
"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
/v4/qr-codes/{qrcode_id}
Gets the QR code with a matching id.
Path Parameters
qrcode_idstringRequired
The QR Code ID
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE500 INTERNAL_ERROR
{
"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"
}
}
},
"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"
}
Retrieve QR Codes by Group
/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.
Query Parameters
has_render_customizationsstring
a filter value if the QRCode has any render customizations (like color or shape
changes)
Default: "both"
Enum: "on""off""both"
archivedstring
a filter value if resource is archived or hidden
Default: "off"
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.
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/{group_guid}/qr-codes?has_
render_customizations=both&archived=both&size=10&search_after=
Response
200 SUCCESS403 FORBIDDEN429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR
{
"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
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans?unit=m
onth&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE500 INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
{
"scans": [
{
"scans": "integer",
"date": "string"
}
],
"units": "integer",
"unit": "string",
"unit_reference": "string"
}
Get Scans Summary for a QR Code
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/summar
y?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-07
00
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE500 INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
{
"total_scans": "integer",
"units": "integer",
"unit": "string",
"unit_reference": "string"
}
Get Scans for a QR Code by Country
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/countr
ies?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A
04%3A05-0700
Response
200 SUCCESS400 BAD_REQUEST403 FORBIDDEN404 NOT_FOUND410
GONE500 INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
json
csv
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"scans": "integer",
"value": "string"
}
]
}
Get Metrics for a QR Code by City
/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)
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"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
/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)
Request
cURLNodeBrowserGoPython
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%3A
04%3A05-0700
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"unit": "string",
"units": "integer",
"facet": "string",
"unit_reference": "string",
"metrics": [
{
"scans": "integer",
"value": "string"
}
]
}
Get Scans for a QR Code by Browser
/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)
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/browse
rs?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A0
4%3A05-0700
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND410 GONE500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
json
csv
{
"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
/v4/user
Update fields in the user
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/user
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/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
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/user/platform_limits?path=%2Forga
nizations%2F%7Borganization_guid%7D
Response
200 SUCCESS403 FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/v4/organizations/{organization_guid}/webhooks
Fetch all webhooks available for an Organization
Path Parameters
organization_guidstringRequired
A GUID for a Bitly organization
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/webhook
s
Response
200 SUCCESS402 UPGRADE_REQUIRED403 FORBIDDEN404 NOT_FOUND429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/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
Request
cURLNodeBrowserGoPython
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
Response
201 CREATED400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND422 UNPROCESSABLE_ENTITY429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/v4/webhooks/{webhook_guid}
Returns a webhook.
Path Parameters
webhook_guidstringRequired
A GUID for a Bitly webhook
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/webhooks/Wa1bcDefG23
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND429 MONTHLY_LIMIT_EXCEEDED500
INTERNAL_ERROR503 TEMPORARILY_UNAVAILABLE
{
"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
/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
Request
cURLNodeBrowserGoPython
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
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND422 UNPROCESSABLE_ENTITY429
MONTHLY_LIMIT_EXCEEDED500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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
/v4/webhooks/{webhook_guid}
Deletes a webhook.
Path Parameters
webhook_guidstringRequired
A GUID for a Bitly webhook
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X DELETE \
https://api-ssl.bitly.com/v4/webhooks/Wa1bcDefG23
Response
204 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
Verify Webhook
/v4/webhooks/{webhook_guid}/verify
Sends ping event to test webhook configuration.
Path Parameters
webhook_guidstringRequired
A GUID for a Bitly webhook
Request
cURLNodeBrowserGoPython
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X POST \
https://api-ssl.bitly.com/v4/webhooks/Wa1bcDefG23/verify
Response
200 SUCCESS400 BAD_REQUEST402 UPGRADE_REQUIRED403
FORBIDDEN404 NOT_FOUND500 INTERNAL_ERROR503
TEMPORARILY_UNAVAILABLE
{
"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"
}