Bitly API Reference

Bitly API (4.0.0)

Bitlinks

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

Related Operations:

POST /bitlinks - Create a new bitlink or add a custom keyword to an existing bitlink
PATCH /bitlinks/{bitlink} - Redirect an existing bitlink

Request Body Schema

domainstring

Default: "bit.ly"

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"
    }
  ]
}

Request Body Schema

long_urlstring

URL to be shortened. Required when creating new bitlinks. Cannot be used with bitlink_id.

domainstring

Default: "bit.ly"

group_guidstring

Always include a specific group and custom domain in your shorten calls.

deeplinksarray of object

install_typestring

Enum: "no_install""auto_install""promote_install"

keywordstring

Custom keyword for creating keyword overrides. If provided, creates an override at domain/keyword

bitlink_idstring

Existing bitlink ID to add a keyword override to. Format: domain/hash. Cannot be used with long_url

expiration_atstring

Optional expiration timestamp for the bitlink (e.g., 2025-01-28T14:30:00+0000). Minimum expiration time is 5 minutes from now and maximum is 1 year.

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"
  ]
}' \
https://api-ssl.bitly.com/v4/bitlinks

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

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"
    }
  ]
}

Path Parameters

bitlinkstringRequired

A Bitlink made of the domain and hash

Request Body Schema

deeplinksarray of object

osstring

Enum: "ios""android"

install_typestring

Enum: "no_install""auto_install""promote_install"

createdstring

ISO timestamp

modifiedstring

ISO timestamp

expiration_atstring

Optional expiration timestamp for the bitlink (e.g., 2025-01-28T14:30:00+0000). Minimum expiration time is 5 minutes from now and maximum is 1 year.

curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "title": "Bitly API Documentation",
  "archived": false,
  "tags": [
    "bitly",
    "api"
  ],
  "deeplinks": [
    {
      "guid": "Ra1bcD2eF3h",
      "bitlink": "bit.ly/documentation",
      "app_uri_path": "/store?id=123456",
      "install_url": "https://play.google.com/store/apps/details?id=com.bitly.app&hl=en_US",
      "app_guid": "Ab1cdE2fG3h",
      "os": "android",
      "install_type": "promote_install",
      "brand_guid": "Ba1bc23dE4F"
    }
  ]
}' \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c

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

Path Parameters

bitlinkstringRequired

A Bitlink made of the domain and hash

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c

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

Request Body Schema

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"
}

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"
}

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

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"
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/engagements?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "engagements": [
    {
      "engagement_count": "integer",
      "engagements": {
        "lib_button_clicks": "integer",
        "clicks": "integer",
        "scans": "integer"
      },
      "date": "string"
    }
  ],
  "units": "integer",
  "unit": "string",
  "unit_reference": "string"
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/engagements/summary?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "total_engagements": "integer",
  "engagements": {
    "lib_button_clicks": "integer",
    "clicks": "integer",
    "scans": "integer"
  },
  "units": "integer",
  "unit": "string",
  "unit_reference": "string"
}

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

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"
    }
  ]
}

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

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"
  }
}

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

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"
    }
  ]
}

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

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"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/12a4b6c/referrer_name?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

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

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"
    }
  ]
}

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

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"
        }
      ]
    }
  ]
}

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

hostname_path_querystring

The hostname and/or path you would like to search (case-insensitive). Subdomains included; query params and fragment ignored.

created_beforeinteger

Timestamp as an integer unix epoch (seconds only)

created_afterinteger

Timestamp as an integer unix epoch (seconds only)

archivedstring

Whether or not to include archived resources

Default: "off"

Enum: "on""off""both"

deeplinksstring

Filter to only Bitlinks that contain deeplinks

Default: "both"

Enum: "on""off""both"

domain_deeplinksstring

Filter to only Bitlinks that contain deeplinks configured with a custom domain

Default: "both"

Enum: "on""off""both"

campaign_guidstring

Filter to return only links for the given campaign GUID, can be provided

channel_guidstring

Filter to return only links for the given channel GUID, can be provided, overrides all other parameters

custom_bitlinkstring

Default: "both"

Enum: "on""off""both"

has_qr_codesstring

a filter value if the resource has any QR codes

Default: "both"

Enum: "on""off""both"

tagsarray

Filter by given tags

launchpad_idsarray

Filter by launchpad id

encoding_loginarray

Filter by the login of the authenticated user that created the Bitlink

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/bitlinks?size=10&search_after=&query=api&hostname_path_query=dev.bitly.com%2Fapi-reference&created_before=1694529902&created_after=1694529902&archived=both&deeplinks=both&domain_deeplinks=both&campaign_guid=Ca1bcd2EFGh&channel_guid=Ha1bc2DefGh&custom_bitlink=both&has_qr_codes=both&tags=bitly&tags=api&launchpad_ids=M1234567890&encoding_login=chauncey

{
  "links": [
    {
      "references": { "any" },
      "link": "string",
      "id": "string",
      "long_url": "string",
      "title": "string",
      "archived": "boolean",
      "created_at": "string",
      "created_by": "string",
      "client_id": "string",
      "custom_bitlinks": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "launchpad_ids": [
        "string"
      ],
      "qr_code_ids": [
        "string"
      ],
      "deeplinks": [
        {
          "guid": "string",
          "bitlink": "string",
          "app_uri_path": "string",
          "install_url": "string",
          "app_guid": "string",
          "os": "string",
          "install_type": "string",
          "created": "string",
          "modified": "string",
          "brand_guid": "string"
        }
      ],
      "campaign_ids": [
        "string"
      ],
      "expiration_at": "string"
    }
  ],
  "pagination": {
    "next": "string",
    "search_after": "string",
    "size": "integer"
  }
}

Path Parameters

group_guidstringRequired

A GUID for a Bitly group

Request Body Schema

actionstringRequired

archive or edit_tags

Enum: "archive""edit_tags"

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"
  ]
}

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

sizeinteger

The quantity of items to be be returned

Default: 50

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/bitlinks/clicks?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700&size=10

{
  "links": [
    {
      "references": { "any" },
      "link": "string",
      "id": "string",
      "long_url": "string",
      "title": "string",
      "archived": "boolean",
      "created_at": "string",
      "created_by": "string",
      "client_id": "string",
      "custom_bitlinks": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "launchpad_ids": [
        "string"
      ],
      "qr_code_ids": [
        "string"
      ],
      "deeplinks": [
        {
          "guid": "string",
          "bitlink": "string",
          "app_uri_path": "string",
          "install_url": "string",
          "app_guid": "string",
          "os": "string",
          "install_type": "string",
          "created": "string",
          "modified": "string",
          "brand_guid": "string"
        }
      ],
      "campaign_ids": [
        "string"
      ],
      "expiration_at": "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.

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

Campaigns

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

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"
    }
  ]
}

Request Body Schema

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"
}

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"
}

Path Parameters

campaign_guidstringRequired

A GUID for a Bitly campaign

Request Body Schema

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"
}

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" }
    }
  ]
}

Request Body Schema

createdstring

ISO TIMESTAMP

modifiedstring

ISO_TIMESTAMP

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" }
}

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" }
}

Path Parameters

channel_guidstringRequired

A GUID for a Bitly Channel

Request Body Schema

createdstring

ISO TIMESTAMP

modifiedstring

ISO_TIMESTAMP

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.

Request Body Schema

curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "custom_bitlink": "chauncey.ly/documentation",
  "bitlink_id": "chauncey.ly/1234abcd"
}' \
https://api-ssl.bitly.com/v4/custom_bitlinks

{
  "custom_bitlink": "string",
  "bitlink": {
    "references": { "any" },
    "link": "string",
    "id": "string",
    "long_url": "string",
    "title": "string",
    "archived": "boolean",
    "created_at": "string",
    "created_by": "string",
    "client_id": "string",
    "custom_bitlinks": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "launchpad_ids": [
      "string"
    ],
    "qr_code_ids": [
      "string"
    ],
    "deeplinks": [
      {
        "guid": "string",
        "bitlink": "string",
        "app_uri_path": "string",
        "install_url": "string",
        "app_guid": "string",
        "os": "string",
        "install_type": "string",
        "created": "string",
        "modified": "string",
        "brand_guid": "string"
      }
    ],
    "campaign_ids": [
      "string"
    ],
    "expiration_at": "string"
  },
  "bitlink_history": [
    {
      "group_guid": "string",
      "keyword": "string",
      "bsd": "string",
      "hash": "string",
      "login": "string",
      "long_url": "string",
      "created": "string",
      "first_created": "string",
      "deactivated": "string",
      "is_active": "boolean"
    }
  ]
}

Path Parameters

custom_bitlinkstringRequired

A Custom Bitlink made of the domain and keyword

Request Body Schema

curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "bitlink_id": "chauncey.ly/1234abcd"
}' \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chauncey

{
  "custom_bitlink": "string",
  "bitlink": {
    "references": { "any" },
    "link": "string",
    "id": "string",
    "long_url": "string",
    "title": "string",
    "archived": "boolean",
    "created_at": "string",
    "created_by": "string",
    "client_id": "string",
    "custom_bitlinks": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "launchpad_ids": [
      "string"
    ],
    "qr_code_ids": [
      "string"
    ],
    "deeplinks": [
      {
        "guid": "string",
        "bitlink": "string",
        "app_uri_path": "string",
        "install_url": "string",
        "app_guid": "string",
        "os": "string",
        "install_type": "string",
        "created": "string",
        "modified": "string",
        "brand_guid": "string"
      }
    ],
    "campaign_ids": [
      "string"
    ],
    "expiration_at": "string"
  },
  "bitlink_history": [
    {
      "group_guid": "string",
      "keyword": "string",
      "bsd": "string",
      "hash": "string",
      "login": "string",
      "long_url": "string",
      "created": "string",
      "first_created": "string",
      "deactivated": "string",
      "is_active": "boolean"
    }
  ]
}

Path Parameters

custom_bitlinkstringRequired

A Custom Bitlink made of the domain and keyword

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/custom_bitlinks/chauncey.ly/chauncey

{
  "custom_bitlink": "string",
  "bitlink": {
    "references": { "any" },
    "link": "string",
    "id": "string",
    "long_url": "string",
    "title": "string",
    "archived": "boolean",
    "created_at": "string",
    "created_by": "string",
    "client_id": "string",
    "custom_bitlinks": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "launchpad_ids": [
      "string"
    ],
    "qr_code_ids": [
      "string"
    ],
    "deeplinks": [
      {
        "guid": "string",
        "bitlink": "string",
        "app_uri_path": "string",
        "install_url": "string",
        "app_guid": "string",
        "os": "string",
        "install_type": "string",
        "created": "string",
        "modified": "string",
        "brand_guid": "string"
      }
    ],
    "campaign_ids": [
      "string"
    ],
    "expiration_at": "string"
  },
  "bitlink_history": [
    {
      "group_guid": "string",
      "keyword": "string",
      "bsd": "string",
      "hash": "string",
      "login": "string",
      "long_url": "string",
      "created": "string",
      "first_created": "string",
      "deactivated": "string",
      "is_active": "boolean"
    }
  ]
}

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

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"
    }
  ]
}

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

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.

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"
      ]
    }
  ]
}

Path Parameters

group_guidstringRequired

A GUID for a Bitly group

Request Body Schema

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"
  ]
}

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"
  ]
}

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"
}

Path Parameters

group_guidstringRequired

A GUID for a Bitly group

Request Body Schema

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"
}

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

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"
    }
  ]
}

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

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"
    }
  ]
}

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

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"
  }
}

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

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"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/referring_networks?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/referrers?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "clicks": "integer",
      "value": "string"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/engagements/top?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "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"
      ],
      "expiration_at": "string"
    }
  ],
  "sorted_links": [
    {
      "clicks": "integer",
      "id": "string"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/engagements/over_time?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "unit_reference": "string",
  "data": [
    {
      "ts": "string",
      "count": "integer"
    }
  ]
}

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

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"
    }
  ]
}

Path Parameters

group_guidstringRequired

A GUID for a Bitly group

Query Parameters

namearray

The limit name you would like usage for

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/feature_usage?name=qr_codes

{
  "group_guid": "string",
  "limit_usage": [
    {
      "name": "string",
      "description": "string",
      "count": "integer"
    }
  ]
}

Path Parameters

group_guidstringRequired

A GUID for a Bitly group

Query Parameters

namearray

The limit name you would like usage for

start_datestring

The start date for the date range

end_datestring

The end date for the date range

unitstring

A unit of time (day, week, or month)

Default: "month"

Enum: "day""week""month"

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/historical_usage?name=qr_codes&start_date=2022-02-02&end_date=2023-10-04&unit=month

{
  "group_guid": "string",
  "unit": "string",
  "start_date": "string",
  "end_date": "string",
  "historical_limit_usage": [
    {
      "name": "string",
      "usage": [
        {
          "count": "integer",
          "unit_start": "string"
        }
      ]
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/links/clicks/over_time?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "unit_reference": "string",
  "data": [
    {
      "ts": "string",
      "count": "integer"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/links/clicks/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",
      "value": "string"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/links/clicks/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"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/links/clicks/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"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/links/clicks/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"
  }
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/links/clicks/top?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "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"
      ],
      "expiration_at": "string"
    }
  ],
  "sorted_links": [
    {
      "clicks": "integer",
      "id": "string"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/codes/scans/over_time?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "unit_reference": "string",
  "data": [
    {
      "ts": "string",
      "count": "integer"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/codes/scans/countries?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"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/codes/scans/cities?unit=month&units=1&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"
  }
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/codes/scans/top?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "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"
      ],
      "expiration_at": "string"
    }
  ],
  "sorted_links": [
    {
      "clicks": "integer",
      "id": "string"
    }
  ]
}

Organizations

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

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"
      ]
    }
  ]
}

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"
  ]
}

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

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"
    }
  ]
}

Path Parameters

organization_guidstringRequired

A GUID for a Bitly organization

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/shorten_counts_by_group

{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "key": "string",
      "value": "integer"
    }
  ]
}

Path Parameters

organization_guidstringRequired

A GUID for a Bitly organization

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/organizations/Oa1bcd234eF/plan_limits

{
  "references": { "any" },
  "organization_guid": "string",
  "plan_limits": [
    {
      "name": "string",
      "description": "string",
      "limit": "integer",
      "count": "integer"
    }
  ]
}

QR Codes

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

Request Body Schema

titlestring

The title of the QR Code

group_guidstringRequired

Identify which group to place the QR Code.

render_customizationsobject

Options for customizing a QR Code's appearance

background_colorstring

The QR code's background color in hex code format with values for alpha channel

dot_pattern_colorstring

The QR code's dot pattern color in hex code format

dot_pattern_typestring

Default: "standard"

Enum: "standard""circle""block""blob""rounded""vertical""horizontal""triangle""heart""star""diamond"

cornersobject

An object representing all three corners of the QR code. The corners corresponding to each property are: corner_1 = top left, corner_2 = top right, and corner_3 = bottom right

corner_1object

Represents one corner, both inner and outer, of a QR code, with color and shape values

inner_colorstring

The inner color of a corner of the QR code in hex code format

outer_colorstring

The outer color of a corner of the QR code in hex code format

shapestring

The shape one of the QR code's corners should take

Default: "standard"

Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"

corner_2object

Represents one corner, both inner and outer, of a QR code, with color and shape values

inner_colorstring

The inner color of a corner of the QR code in hex code format

outer_colorstring

The outer color of a corner of the QR code in hex code format

shapestring

The shape one of the QR code's corners should take

Default: "standard"

Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"

corner_3object

Represents one corner, both inner and outer, of a QR code, with color and shape values

inner_colorstring

The inner color of a corner of the QR code in hex code format

outer_colorstring

The outer color of a corner of the QR code in hex code format

shapestring

The shape one of the QR code's corners should take

Default: "standard"

Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"

gradientobject

stylestring

The style of the gradient. Can be either linear or radial.

Default: "no_gradient"

Enum: "no_gradient""linear""radial"

anglenumber

The angle by which the gradient will be rotated. Only applies to linear gradients.

colorsarray

The list of hex colors and their offsets to be used in the gradient.

exclude_cornersboolean

Ignore gradient mask on corners

background_gradientobject

stylestring

The style of the gradient. Can be either linear or radial.

Default: "no_gradient"

Enum: "no_gradient""linear""radial"

anglenumber

The angle by which the gradient will be rotated. Only applies to linear gradients.

colorsarray

The list of hex colors and their offsets to be used in the gradient.

exclude_cornersboolean

Ignore gradient mask on corners

logoobject

image_guidstring

A GUID for an image uploaded to Bitly

frameobject

idstring

The unique id of the selected frame

Default: "none"

Enum: "none""border_only""text_bottom""tooltip_bottom""arrow""text_top""text_bottom_in_frame""script""text_top_and_bottom""url""instagram"

colorsobject

An object of named colors denoting which color should go to which area of the frame

primarystring

The primary color of the frame in hex code format

secondarystring

The secondary color of the frame in hex code format

backgroundstring

The background color of the frame in hex code format

textobject

The text to be inserted into the QR code's frame

primaryobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

secondaryobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

textobject

Contains the center, top, and bottom text to be used in the QR code

centerobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

topobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

bottomobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

brandingobject

bitly_brandboolean

A boolean that determines if the QR code should have the bitly brand in its bottom right corner

spec_settingsobject

The QR code's editable spec settings, which for now is just the error correction

error_correctioninteger

The amount of error correction that the QR code was generated with

archivedboolean

A boolean representing if the QR code should be archived (hidden from the UI) upon creation

destinationobjectRequired

gs1object

Contains GS1 related metadata

valuesarray

A list of GS1 application identifiers and their values

expiration_atstring

Optional expiration timestamp for the QR code's bitlink (e.g., 2025-01-28T14:30:00+0000). Minimum expiration time is 5 minutes from now and maximum is 1 year.

tagsarray of string

A list of tags to add to the QR code

curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "title": "A QR Code",
  "group_guid": "Ba1bc23dE4F",
  "destination": {
    "bitlink_id": "bit.ly/abc123"
  },
  "archived": false,
  "tags": [
    "tag1",
    "tag2"
  ],
  "render_customizations": {
    "background_color": "#ffffff",
    "dot_pattern_color": "#EF8000",
    "dot_pattern_type": "rounded",
    "corners": {
      "corner_1": {
        "inner_color": "#EF8000",
        "outer_color": "#EF8000",
        "shape": "leaf"
      },
      "corner_2": {
        "inner_color": "#EF8000",
        "outer_color": "#EF8000",
        "shape": "leaf"
      },
      "corner_3": {
        "inner_color": "#EF8000",
        "outer_color": "#EF8000",
        "shape": "leaf"
      }
    },
    "gradient": {
      "style": "linear",
      "angle": 45,
      "colors": [
        {
          "color": "#c80404",
          "offset": 10
        },
        {
          "color": "#042f86",
          "offset": 90
        }
      ],
      "exclude_corners": false
    },
    "background_gradient": {
      "style": "radial",
      "colors": [
        {
          "color": "#c696ee",
          "offset": 25
        },
        {
          "color": "#d4e1a8",
          "offset": 50
        }
      ]
    },
    "logo": {
      "image_guid": "bitlylogo"
    },
    "frame": {
      "id": "text_bottom",
      "colors": {
        "primary": "#f55656",
        "background": "#ffffff"
      },
      "text": {
        "primary": {
          "content": "QR Frame"
        },
        "secondary": {
          "content": "Frame Text"
        }
      }
    },
    "branding": {
      "bitly_brand": true
    },
    "spec_settings": {
      "error_correction": 4
    }
  }
}' \
https://api-ssl.bitly.com/v4/qr-codes

{
  "qrcode_id": "string",
  "group_guid": "string",
  "title": "string",
  "is_customized": "boolean",
  "serialized_content": "string",
  "qr_code_type": "string",
  "long_urls": [
    "string"
  ],
  "bitlink_id": "string",
  "is_gs1": "boolean",
  "created_by": "string",
  "tags": [
    "string"
  ],
  "archived": "boolean",
  "expiration_at": "string",
  "created": "string",
  "modified": "string"
}

Header Parameters

Acceptstring

Controls the response format. Use `application/json` (default) to receive a JSON-wrapped base64 image, `image/svg+xml` to receive the raw SVG, or `image/png` to receive the raw PNG.

Enum: "application/json""image/svg+xml""image/png"

Query Parameters

formatstring

The image format. Supports `svg` and `png`. Ignored if the Accept header specifies an image type.

Default: "svg"

Enum: "svg""png"

Request Body Schema

contentstringRequired

The raw content to encode in the QR code (e.g. a URL).

group_guidstringRequired

The group (brand) GUID used for access control and analytics.

render_customizationsobject

Appearance options for a static QR code. gradient, background_gradient, frame, text, and logo are not supported.

background_colorstring

The QR code's background color in hex code format with values for alpha channel

dot_pattern_colorstring

The QR code's dot pattern color in hex code format

dot_pattern_typestring

Default: "standard"

Enum: "standard""circle""block""blob""rounded""vertical""horizontal""triangle""heart""star""diamond"

cornersobject

An object representing all three corners of the QR code. The corners corresponding to each property are: corner_1 = top left, corner_2 = top right, and corner_3 = bottom right

corner_1object

Represents one corner, both inner and outer, of a QR code, with color and shape values

inner_colorstring

The inner color of a corner of the QR code in hex code format

outer_colorstring

The outer color of a corner of the QR code in hex code format

shapestring

The shape one of the QR code's corners should take

Default: "standard"

Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"

corner_2object

Represents one corner, both inner and outer, of a QR code, with color and shape values

inner_colorstring

The inner color of a corner of the QR code in hex code format

outer_colorstring

The outer color of a corner of the QR code in hex code format

shapestring

The shape one of the QR code's corners should take

Default: "standard"

Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"

corner_3object

Represents one corner, both inner and outer, of a QR code, with color and shape values

inner_colorstring

The inner color of a corner of the QR code in hex code format

outer_colorstring

The outer color of a corner of the QR code in hex code format

shapestring

The shape one of the QR code's corners should take

Default: "standard"

Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-H 'Accept: image/svg+xml' \
-X POST \
-d '{
  "content": "https://bitly.com",
  "group_guid": "Ba1bc23dE4F",
  "render_customizations": {
    "background_color": "#ffffff",
    "dot_pattern_color": "#EF8000",
    "dot_pattern_type": "rounded"
  }
}' \
https://api-ssl.bitly.com/v4/qr-codes/static?format=

Header Parameters

Acceptstring

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

Path Parameters

qrcode_idstringRequired

The QR Code ID

Query Parameters

formatstring

The format type of the image. If there is an image format in the header it takes precedence.

Default: "svg"

Enum: "svg""png"

curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Accept: image/svg+xml' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/image?format=

{
  "qr_code_image": "string"
}

Path Parameters

qrcode_idstringRequired

The QR code ID

Request Body Schema

render_customizationsobject

Options for customizing a QR Code's appearance

background_colorstring

The QR code's background color in hex code format with values for alpha channel

dot_pattern_colorstring

The QR code's dot pattern color in hex code format

dot_pattern_typestring

Default: "standard"

Enum: "standard""circle""block""blob""rounded""vertical""horizontal""triangle""heart""star""diamond"

cornersobject

An object representing all three corners of the QR code. The corners corresponding to each property are: corner_1 = top left, corner_2 = top right, and corner_3 = bottom right

corner_1object

Represents one corner, both inner and outer, of a QR code, with color and shape values

inner_colorstring

The inner color of a corner of the QR code in hex code format

outer_colorstring

The outer color of a corner of the QR code in hex code format

shapestring

The shape one of the QR code's corners should take

Default: "standard"

Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"

corner_2object

Represents one corner, both inner and outer, of a QR code, with color and shape values

inner_colorstring

The inner color of a corner of the QR code in hex code format

outer_colorstring

The outer color of a corner of the QR code in hex code format

shapestring

The shape one of the QR code's corners should take

Default: "standard"

Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"

corner_3object

Represents one corner, both inner and outer, of a QR code, with color and shape values

inner_colorstring

The inner color of a corner of the QR code in hex code format

outer_colorstring

The outer color of a corner of the QR code in hex code format

shapestring

The shape one of the QR code's corners should take

Default: "standard"

Enum: "standard""slightly_round""rounded""extra_round""leaf""leaf_inner""leaf_outer""target""concave"

gradientobject

stylestring

The style of the gradient. Can be either linear or radial.

Default: "no_gradient"

Enum: "no_gradient""linear""radial"

anglenumber

The angle by which the gradient will be rotated. Only applies to linear gradients.

colorsarray

The list of hex colors and their offsets to be used in the gradient.

exclude_cornersboolean

Ignore gradient mask on corners

background_gradientobject

stylestring

The style of the gradient. Can be either linear or radial.

Default: "no_gradient"

Enum: "no_gradient""linear""radial"

anglenumber

The angle by which the gradient will be rotated. Only applies to linear gradients.

colorsarray

The list of hex colors and their offsets to be used in the gradient.

exclude_cornersboolean

Ignore gradient mask on corners

logoobject

image_guidstring

A GUID for an image uploaded to Bitly

frameobject

idstring

The unique id of the selected frame

Default: "none"

Enum: "none""border_only""text_bottom""tooltip_bottom""arrow""text_top""text_bottom_in_frame""script""text_top_and_bottom""url""instagram"

colorsobject

An object of named colors denoting which color should go to which area of the frame

primarystring

The primary color of the frame in hex code format

secondarystring

The secondary color of the frame in hex code format

backgroundstring

The background color of the frame in hex code format

textobject

The text to be inserted into the QR code's frame

primaryobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

secondaryobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

textobject

Contains the center, top, and bottom text to be used in the QR code

centerobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

topobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

bottomobject

An object describing text with color

contentstring

The text to be used

colorstring

The color of the text in hex code format

Default: "#ffffff"

brandingobject

bitly_brandboolean

A boolean that determines if the QR code should have the bitly brand in its bottom right corner

spec_settingsobject

The QR code's editable spec settings, which for now is just the error correction

error_correctioninteger

The amount of error correction that the QR code was generated with

archivedboolean

A boolean representing if the QR code has been archived

expiration_atstring

Optional expiration timestamp for the QR code's bitlink (e.g., 2025-01-28T14:30:00+0000). Minimum expiration time is 5 minutes from now and maximum is 1 year.

tagsarray of string

A list of tags to add to the QR code

curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
  "title": "Updated Title",
  "archived": true,
  "tags": [
    "tag1",
    "tag2"
  ],
  "render_customizations": {
    "background_color": "#ffffff",
    "dot_pattern_color": "#EF8000",
    "dot_pattern_type": "rounded",
    "corners": {
      "corner_1": {
        "inner_color": "#EF8000",
        "outer_color": "#EF8000",
        "shape": "leaf"
      },
      "corner_2": {
        "inner_color": "#EF8000",
        "outer_color": "#EF8000",
        "shape": "leaf"
      },
      "corner_3": {
        "inner_color": "#EF8000",
        "outer_color": "#EF8000",
        "shape": "leaf"
      }
    },
    "gradient": {
      "style": "linear",
      "angle": 45,
      "colors": [
        {
          "color": "#c80404",
          "offset": 10
        },
        {
          "color": "#042f86",
          "offset": 90
        }
      ],
      "exclude_corners": false
    },
    "background_gradient": {
      "style": "radial",
      "colors": [
        {
          "color": "#c696ee",
          "offset": 25
        },
        {
          "color": "#d4e1a8",
          "offset": 50
        }
      ]
    },
    "logo": {
      "image_guid": "bitlylogo"
    },
    "frame": {
      "id": "text_bottom",
      "colors": {
        "primary": "#f55656",
        "background": "#ffffff"
      },
      "text": {
        "primary": {
          "content": "QR Frame"
        },
        "secondary": {
          "content": "Frame Text"
        }
      }
    },
    "branding": {
      "bitly_brand": true
    },
    "spec_settings": {
      "error_correction": 4
    }
  }
}' \
https://api-ssl.bitly.com/v4/qr-codes/Qabc123

{
  "qrcode_id": "string",
  "group_guid": "string",
  "title": "string",
  "is_customized": "boolean",
  "serialized_content": "string",
  "qr_code_type": "string",
  "long_urls": [
    "string"
  ],
  "bitlink_id": "string",
  "is_gs1": "boolean",
  "created_by": "string",
  "tags": [
    "string"
  ],
  "archived": "boolean",
  "expiration_at": "string",
  "created": "string",
  "modified": "string"
}

Path Parameters

qrcode_idstringRequired

The QR Code ID

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345

{
  "qrcode_id": "string",
  "group_guid": "string",
  "title": "string",
  "gs1": {
    "values": [
      {
        "key": "string",
        "value": "string"
      }
    ]
  },
  "render_customizations": {
    "background_color": "string",
    "dot_pattern_color": "string",
    "dot_pattern_type": "string",
    "corners": {
      "corner_1": {
        "inner_color": "string",
        "outer_color": "string",
        "shape": "string"
      },
      "corner_2": {
        "inner_color": "string",
        "outer_color": "string",
        "shape": "string"
      },
      "corner_3": {
        "inner_color": "string",
        "outer_color": "string",
        "shape": "string"
      }
    },
    "gradient": {
      "style": "string",
      "angle": "number",
      "colors": [
        {
          "color": "string",
          "offset": "integer"
        }
      ],
      "exclude_corners": "boolean"
    },
    "background_gradient": {
      "style": "string",
      "angle": "number",
      "colors": [
        {
          "color": "string",
          "offset": "integer"
        }
      ],
      "exclude_corners": "boolean"
    },
    "logo": {
      "image_guid": "string"
    },
    "frame": {
      "id": "string",
      "colors": {
        "primary": "string",
        "secondary": "string",
        "background": "string"
      },
      "text": {
        "primary": {
          "content": "string",
          "color": "string"
        },
        "secondary": {
          "content": "string",
          "color": "string"
        }
      }
    },
    "text": {
      "center": {
        "content": "string",
        "color": "string"
      },
      "top": {
        "content": "string",
        "color": "string"
      },
      "bottom": {
        "content": "string",
        "color": "string"
      }
    },
    "branding": {
      "bitly_brand": "boolean"
    },
    "spec_settings": {
      "error_correction": "integer"
    }
  },
  "qr_code_type": "string",
  "bitlink_id": "string",
  "long_urls": [
    "string"
  ],
  "serialized_content": "string",
  "archived": "boolean",
  "created": "string",
  "modified": "string",
  "expiration_at": "string"
}

Path Parameters

qrcode_idstringRequired

The QR Code ID

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X DELETE \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345

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

Path Parameters

group_guidstringRequired

A GUID for a Bitly group

Query Parameters

has_render_customizationsstring

Whether or not QRCode has any render customizations (like color or shape changes)

Default: "both"

Enum: "on""off""both"

sizeinteger

The quantity of items to be be returned

Default: 50

search_afterstring

Token used to search next batch of qr codes, only use response from API as input value.

querystring

The value that you would like to search

hostname_path_querystring

The hostname and/or path you would like to search (case-insensitive). Subdomains included; query params and fragment ignored.

created_beforeinteger

Timestamp as an integer unix epoch (seconds only)

created_afterinteger

Timestamp as an integer unix epoch (seconds only)

archivedstring

Whether or not to include archived resources

Default: "off"

Enum: "on""off""both"

creating_loginarray

Filter by the login of the authenticated user that created the QR Code

qrc_typearray

Default: ["bitlink", "long_url"]

is_gs1string

a filter value if the resource is a GS1 QR code

Default: "both"

Enum: "on""off""both"

tagsarray

Filter by given tags

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/groups/Ba1bc23dE4F/qr-codes?has_render_customizations=both&size=10&search_after=&query=api&hostname_path_query=dev.bitly.com%2Fapi-reference&created_before=1694529902&created_after=1694529902&archived=both&creating_login=chauncey&qrc_type=&is_gs1=both&tags=bitly&tags=api

{
  "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",
      "tags": [
        "string"
      ],
      "archived": "boolean",
      "expiration_at": "string",
      "created": "string",
      "modified": "string"
    }
  ],
  "pagination": {
    "next": "string",
    "search_after": "string",
    "size": "integer"
  }
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "scans": [
    {
      "scans": "integer",
      "date": "string"
    }
  ],
  "units": "integer",
  "unit": "string",
  "unit_reference": "string"
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/summary?unit=month&units=1&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "total_scans": "integer",
  "units": "integer",
  "unit": "string",
  "unit_reference": "string"
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/countries?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "scans": "integer",
      "value": "string"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/cities?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "scans": "integer",
      "city": "string",
      "subregion": "string",
      "region": "string",
      "country": "string"
    }
  ],
  "other_metrics": {
    "other_city_scans": "integer",
    "no_city_scans": "integer"
  }
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/device_os?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "scans": "integer",
      "value": "string"
    }
  ]
}

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

curl \
-H 'Authorization: Bearer {TOKEN}' \
-X GET \
https://api-ssl.bitly.com/v4/qr-codes/Qabcde12345/scans/browsers?unit=month&units=1&size=10&unit_reference=2006-01-02T15%3A04%3A05-0700

{
  "unit": "string",
  "units": "integer",
  "facet": "string",
  "unit_reference": "string",
  "metrics": [
    {
      "scans": "integer",
      "value": "string"
    }
  ]
}

User

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

Request Body Schema

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"
}

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"
}

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.

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"
    }
  ]
}

Request Body Schema

organization_guidstringRequired

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"
}

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"
}

Path Parameters

webhook_guidstringRequired

A GUID for a Bitly webhook

Request Body Schema

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"
}

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

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"
}