Bitly

Bitly

Bitly is a URL shortening, QR code, and link management platform. Shorten URLs, create branded QR codes, organize links into campaigns and channels, track click/engagement analytics by geography, device, and referrer, and manage branded short domains (BSDs).

Entity Hierarchy

• Organization → top-level account container, has organization_guid. Owns plan limits.
• Group → subdivision within an org, has group_guid. Every user belongs to at least one group. All bitlinks and QR codes live in a group.
• Bitlink → a shortened URL, identified by domain/hash (e.g. bit.ly/abc123). The id field is this same format.
• Custom Bitlink → a branded vanity URL on a BSD (e.g. yourco.link/campaign). Attached to an existing bitlink.
• QR Code → a scannable code linked to a URL. Customizable dot patterns, colors, corners. Has a qr_code_id.
• Campaign → organizes links for marketing, has guid. Scoped to a group.
• Channel → distribution channel within a campaign, has guid. Scoped to a group.
• BSD (Branded Short Domain) → custom domain for branded links (e.g. yourco.link). Assigned to groups.

Workflows

Shorten a URL

Provide the long URL. Optionally specify a group, domain, title, and tags. Returns the new bitlink with its short URL.

Create branded vanity URLs

First shorten, then attach a custom keyword on a BSD with the custom bitlinks tool. E.g. map yourco.link/launch to bit.ly/3xYzAbc. List BSDs first to know which domains are available.

Create QR codes

Create customizable QR codes for any URL. Configure dot patterns (circle, blob, diamond, etc.), corner shapes, colors, and gradients. QR codes auto-shorten their destination URL.

Get a link dashboard

Use the link dashboard tool for a one-call overview: metadata + click summary + engagement summary in a single response.

Analyze link performance

Get click counts over time with configurable time windows. Drill into geographic breakdowns (country, city), device types, and referrer sources for any bitlink or across an entire group.

Organize with campaigns

Create campaigns to group related links. Assign channels (distribution sources like email, social, etc.) to campaigns. Filter bitlinks by campaign or channel.

Discover account structure

List organizations, then groups within them. Groups expose their BSDs, preferences, shorten counts, and feature usage limits. Use plan limits to understand what actions are available before attempting them.

Time-Range Parameters (Analytics)

Analytics tools accept:

• unit — granularity: minute, hour, day, week, month (default: day)
• units — number of time units to query; -1 returns all available data (default: -1)
• unit_reference — ISO-8601 timestamp for the end of the range (default: now)

Gotchas

• group_guid required: Most list/create operations are group-scoped. Always resolve the user's default group first.
• Bitlink ID format: Always domain/hash (e.g. bit.ly/3xYzAbc), not just the hash—use the same compound id for analytics and edits.
• Custom bitlink format: yourdomain.com/keyword — the domain must be a BSD on the account.
• QR codes require group_guid: Pass the group when creating. Get QR code image URLs from the response.
• Monthly shorten limits: Bitly enforces per-account monthly caps. Use the plan limits tool to check before shortening in bulk.
• BSD DNS: Creating links on a custom domain requires DNS to be properly configured; otherwise DNS_CONFIGURATION_ERROR.
• Pagination: Long bitlink catalogs use cursor-style paging (not simple numeric offsets).
• Rate limits: Heavy bursts may be throttled; some analytics require higher vendor tiers and return upgrade prompts when blocked.