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
/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
/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
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"
],
"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"
}
],
"is_deleted": "boolean",
"campaign_ids": [
"string"
]
}Delete a Bitlink
/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
/v4/bitlinks/{bitlink}
Updates fields in the specified link. 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
install_typestring
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"
],
"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"
}
],
"is_deleted": "boolean",
"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
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"
],
"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"
}
],
"is_deleted": "boolean",
"campaign_ids": [
"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"
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/qr?image_format=svg{
"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.
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{
"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.
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{
"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"
}Expand a Bitlink
/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
/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
/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
/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
/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
/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
/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 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)
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
/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
/v4/groups/{group_guid}/bitlinks
Returns a paginated collection of Bitlinks for a group.
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 page of links
keywordstring
Custom keyword to filter on history entries
querystring
The value that you would like to search
created_beforeinteger
Timestamp as an integer unix epoch
created_afterinteger
Timestamp as an integer unix epoch
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"
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=page2&keyword=chauncey&query=api&created_before=1501027200&created_after=1501027200&archived=both&deeplinks=both&domain_deeplinks=both&campaign_guid=Ca1bcd2EFGh&channel_guid=Ha1bc2DefGh&custom_bitlink=both&tags%5B0%5D=bitly&tags%5B1%5D=api&launchpad_ids%5B0%5D=M1234567890&encoding_login%5B0%5D=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"
],
"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"
}
],
"is_deleted": "boolean",
"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
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
/v4/groups/{group_guid}/bitlinks/{sort}
Returns a list of Bitlinks sorted by group.
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"
],
"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"
}
],
"is_deleted": "boolean",
"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.
Group Overrides
/v4/groups/{group_guid}/overrides
retrieves all account overrides matching specified group_guid and bsd query filters.
Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Query Parameters
group_guidarray
GUIDs for a Bitly group
created_afterinteger
Timestamp as an integer unix epoch
limitinteger
limit the amount of results returned
offsetinteger
set the starting index of the result set
bsdarray
a branded short domains to filter results
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/overrides?group_guid%5B0%5D=Ba1bc23dE4F&group_guid%5B1%5D=Br1bc55dE4J&created_after=1501027200&limit=50&offset=50&bsd=nyti.ms{
"overrides": [
{
"references": { "any" },
"id": "string",
"rules": "string",
"version": "integer",
"created": "string",
"modified": "string",
"link": "string",
"group_guid": "string"
}
],
"total_count": "integer"
}Get BSDs
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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"
],
"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"
}
],
"is_deleted": "boolean",
"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"
}
]
}Update Custom Bitlink
/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"
],
"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"
}
],
"is_deleted": "boolean",
"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
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"
],
"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"
}
],
"is_deleted": "boolean",
"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)
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
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/referring_networks{
"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)
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"
}
]
}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
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/qr/images{
"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.
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
/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
/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 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
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"
}
]
}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 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
/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
/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
/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
/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
/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
/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
/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/Wa1bcDefG23Verify Webhook
/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"
}