BitlyDeveloper
Navigation
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).

Get a QR Code

Get
/v4/bitlinks/{bitlink}/qr

Generates a QR code for a Bitlink.

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/qr
{
  "link": "string",
  "id": "string",
  "qr_code": "string"
}

Get Metrics for a Bitlink by Country

Get
/v4/bitlinks/{bitlink}/countries

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

Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/countries?unit=month&units=5&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Metrics for a Bitlink by City

Get
/v4/bitlinks/{bitlink}/cities

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

Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/cities?unit=month&units=5&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "city": "string",
      "subregion": "string",
      "region": "string",
      "country": "string"
    }
  ],
  "other_metrics": {
    "other_city_clicks": "integer",
    "no_city_clicks": "integer"
  }
}

Get Metrics for a Bitlink by Device Type

Get
/v4/bitlinks/{bitlink}/devices

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

Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/devices?unit=month&units=5&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "device_type": "string"
    }
  ]
}

Get Metrics for a Bitlink by Referrers

Get
/v4/bitlinks/{bitlink}/referrers

Returns referrer click counts for the specified link.

Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/referrers?unit=month&units=5&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Metrics for a Bitlink by Referring Domains

Get
/v4/bitlinks/{bitlink}/referring_domains

Returns the referring domain click counts for the specified link.

Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/referring_domains?unit=month&units=5&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Metrics for a Bitlink by Referrers by Domain

Get
/v4/bitlinks/{bitlink}/referrers_by_domains

Returns click metrics grouped by referrers for the specified link.

Path Parameters
bitlinkstringRequired
A Bitlink made of the domain and hash
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/referrers_by_domains?unit=month&units=5&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "referrers_by_domain": [
    {
      "network": "string",
      "referrers": [
        {
          "key": "string",
          "value": "integer"
        }
      ]
    }
  ]
}

Retrieve Bitlinks by Group

Get
/v4/groups/{group_guid}/bitlinks

Returns a paginated collection of Bitlinks for a group.

Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Query Parameters
sizeinteger
The quantity of items to be be returned
Default: 50
pageinteger
Integer specifying the numbered result at which to start
Default: 1
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
modified_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
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&page=1&keyword=chauncey&query=api&created_before=1501027200&created_after=1501027200&modified_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&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"
      ],
      "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"
        }
      ]
    }
  ],
  "pagination": {
    "prev": "string",
    "next": "string",
    "size": "integer",
    "page": "integer",
    "total": "integer"
  }
}

BSDs

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

Get BSDs

Get
/v4/bsds

Fetch all Branded Short Domains

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

Campaigns

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

Retrieve Campaigns

Get
/v4/campaigns

Returns the campaigns for the current authenticated user.

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

Create Campaign

Post
/v4/campaigns

Creates a new campaign.

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

Retrieve a Campaign

Get
/v4/campaigns/{campaign_guid}

Returns details for a campaign.

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

Update Campaign

Patch
/v4/campaigns/{campaign_guid}

Updates a campaign's details.

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

Retrieve Channels

Get
/v4/channels

Returns the channels available to a user.

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

Create Channel

Post
/v4/channels

Creates a new channel.

Request Body Schema
namestring
guidstring
createdstring
ISO TIMESTAMP
modifiedstring
ISO_TIMESTAMP
group_guidstring
bitlinksarray of object
campaign_guidstring
bitlink_idstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X POST \
https://api-ssl.bitly.com/v4/channels
{
  "name": "string",
  "guid": "string",
  "created": "string",
  "modified": "string",
  "group_guid": "string",
  "references": { "any" }
}

Get a Channel

Get
/v4/channels/{channel_guid}

Returns a channel's details.

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

Update a Channel

Patch
/v4/channels/{channel_guid}

Updates an existing channel.

Path Parameters
channel_guidstringRequired
A GUID for a Bitly Channel
Request Body Schema
namestring
guidstring
createdstring
ISO TIMESTAMP
modifiedstring
ISO_TIMESTAMP
group_guidstring
bitlinksarray of object
campaign_guidstring
bitlink_idstring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X PATCH \
https://api-ssl.bitly.com/v4/channels/Ha1bc2DefGh
{
  "name": "string",
  "guid": "string",
  "created": "string",
  "modified": "string",
  "group_guid": "string",
  "references": { "any" }
}

Custom Bitlinks

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

Get Metrics for a Custom Bitlink by Destination

Get
/v4/custom_bitlinks/{custom_bitlink}/clicks_by_destination

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

Path Parameters
custom_bitlinkstringRequired
A Custom Bitlink made of the domain and keyword
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chauncey/clicks_by_destination?unit=month&units=5&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Groups

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

Retrieve Groups

Get
/v4/groups

Returns a list of groups in the organization.

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

Update a Group

Patch
/v4/groups/{group_guid}

Updates the details of a group.

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

Retrieve a Group

Get
/v4/groups/{group_guid}

Returns details for a group.

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

Retrieve Tags by Group

Get
/v4/groups/{group_guid}/tags

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

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

Retrieve Group Preferences

Get
/v4/groups/{group_guid}/preferences

Returns preferences for the specified group.

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

Update Group Preferences

Patch
/v4/groups/{group_guid}/preferences

Updates preferences for a group.

Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Request Body Schema
group_guidstring
domain_preferencestring
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X PATCH \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/preferences
{
  "group_guid": "string",
  "domain_preference": "string"
}

Retrieve Group Shorten Counts

Get
/v4/groups/{group_guid}/shorten_counts

Returns all the shorten counts for a group.

Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/shorten_counts?unit=month&units=5&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "key": "string",
      "value": "integer"
    }
  ]
}

Get Click Metrics for a Group by Country

Get
/v4/groups/{group_guid}/countries

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

Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/countries?unit=month&units=5&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

Get Click Metrics for a Group by City

Get
/v4/groups/{group_guid}/cities

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

Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/cities?unit=month&units=5&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "city": "string",
      "subregion": "string",
      "region": "string",
      "country": "string"
    }
  ],
  "other_metrics": {
    "other_city_clicks": "integer",
    "no_city_clicks": "integer"
  }
}

Get Click Metrics for a Group by Device Type

Get
/v4/groups/{group_guid}/devices

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

Path Parameters
group_guidstringRequired
A GUID for a Bitly group
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
sizeinteger
The quantity of items to be be returned
Default: 50
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/devices?unit=month&units=5&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700
{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "device_type": "string"
    }
  ]
}

Get Click Metrics for a Group by Referring Networks

Get
/v4/groups/{group_guid}/referring_networks

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

Path Parameters
group_guidstringRequired
A GUID for a Bitly group
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"
    }
  ]
}

Organizations

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

Retrieve Organizations

Get
/v4/organizations

Retrieve a list of organizations.

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

Retrieve an Organization

Get
/v4/organizations/{organization_guid}

Retrive details for the specified organization.

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

Get Shorten Counts for an Organization

Get
/v4/organizations/{organization_guid}/shorten_counts

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

Path Parameters
organization_guidstringRequired
A GUID for a Bitly organization
Query Parameters
unitstringRequired
A unit of time
Default: "day"
Enum: "minute""hour""day""week""month"
unitsintegerRequired
An integer representing the time units to query data for. pass -1 to return all units of time.
Default: -1
unit_referencestring
An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.
curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/shorten_counts?unit=month&units=5&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

Get
/v4/organizations/{organization_guid}/plan_limits

Returns all plan limits and counts available for an organization.

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

User

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

Update a User

Patch
/v4/user

Update fields in the user

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

Retrieve a User

Get
/v4/user

Returns information for the current authenticated user.

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

Get Platform Limits

Get
/v4/user/platform_limits

Fetch all platform limits and counts available for an organization

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

Webhooks

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

Get Webhooks

Get
/v4/organizations/{organization_guid}/webhooks

Fetch all webhooks available for an Organization

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

Create Webhook

Post
/v4/webhooks

Creates a webhook.

Request Body Schema
is_activeboolean
organization_guidstringRequired
group_guidstring
namestringRequired
eventstringRequired
urlstringRequired
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"
}' \
https://api-ssl.bitly.com/v4/webhooks
{
  "references": { "any" },
  "guid": "string",
  "created": "string",
  "modified": "string",
  "modified_by": "string",
  "deactivated": "string",
  "is_active": "boolean",
  "organization_guid": "string",
  "group_guid": "string",
  "name": "string",
  "event": "string",
  "url": "string",
  "status": "string"
}

Retrieve Webhook

Get
/v4/webhooks/{webhook_guid}

Returns a webhook.

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

Update Webhook

Patch
/v4/webhooks/{webhook_guid}

Update a webhook

Path Parameters
webhook_guidstringRequired
A GUID for a Bitly webhook
Request Body Schema
guidstringRequired
is_activeboolean
organization_guidstring
group_guidstring
namestring
eventstring
urlstring
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"
}' \
https://api-ssl.bitly.com/v4/webhooks/Wa1bcDefG23
{
  "references": { "any" },
  "guid": "string",
  "created": "string",
  "modified": "string",
  "modified_by": "string",
  "deactivated": "string",
  "is_active": "boolean",
  "organization_guid": "string",
  "group_guid": "string",
  "name": "string",
  "event": "string",
  "url": "string",
  "status": "string"
}

Delete Webhook

Delete
/v4/webhooks/{webhook_guid}

Deletes a webhook.

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