Use the **Link Shortener API** to shorten and track links

Reliable and fast to help you grow your brand.

## API Designed for Ease  
We have optimized for ease of implementation. All API methods are accessible via simple HTTP calls. Most implementations of this API take less than 15 minutes to setup. Simply call the provided URLs with their respective parameters, and you're done.

## Getting Started: Authentication  
All API endpoints require API authentication credentials to be supplied as query arguments. To get started, you'll need a free [Shareaholic account](/content/signup/index.html) and Site ID. Signup for an account and then [add your site](/content/sites/index.html) to get your Site ID. The Site ID is your API Key for the URL Shortener API.

Example:

```html
...&apikey=8943b7fd64cd8b1770ff5affa9a9437b&...
```

Note: the apikey used in this document is intended for use as an example only. It is subject to change.

## Parameters  
Endpoint:`https://www.shareaholic.com/v2/share/shorten_link/`

| Parameter | Description | Required | Example |
| --- | --- | --- | --- |
| `url` | URL to shorten | Required | url=http://www.google.com/ |
| `apikey` | API Key | Required | apikey=8943b7fd64cd8b1770ff5affa9a9437b |
| `service[name]` | Shortener Service | Optional | service[name]=shrlc (shrlc|bitly|tinyurl) |
| `service[token]` | Service Authentication | Optional | service[token]=0642e640dc831a3f32b68e579acssdbeaab1b360 |
| `service[domain]` | Custom Short Domain (Bitly Branded Short Domain) | Optional | service[domain]=yourbrand.co |

Working Example:

```html
https://www.shareaholic.com/v2/share/shorten_link?apikey=8943b7fd64cd8b1770ff5affa9a9437b&url=http://google.com/&service[name]=shrlc
```

You may use your own [Bitly Generic Access Token](https://bitly.is/accesstoken) by passing in an additional `service[token]` parameter. When set, the URL Shortener API will use your personal key to shorten the link.

```html
https://www.shareaholic.com/v2/share/shorten_link?apikey=8943b7fd64cd8b1770ff5affa9a9437b&url=http://google.com/&service[name]=bitly&service[token]=[INSERT YOUR BITLY Generic Access Token]
```

If you have a [Bitly Branded Short Domain](https://support.bitly.com/hc/en-us/articles/230558107-What-is-a-custom-domain) (BSD), you can pass it via the `service[domain]` parameter to shorten links using your custom domain.

```html
https://www.shareaholic.com/v2/share/shorten_link?apikey=8943b7fd64cd8b1770ff5affa9a9437b&url=http://google.com/&service[name]=bitly&service[token]=[YOUR TOKEN]&service[domain]=yourbrand.co
```

Note: If `service[name]` is omitted, the API will use the shortener configured for the given site profile. If you have connected Bitly to your site profile, the API will automatically use your stored Bitly credentials and Branded Short Domain.

Example success response:

```json
{
  "status_code": "200",
  "data": "https://go.shr.lc/2sZ8JZo"
}
```

Example error response:

```json
{
  "errors": [
    {
      "code": "140",
      "source": {
        "pointer": "/data/attributes/url"
      },
      "detail": "Missing URL. See https://www.shareaholic.com/api/shortener/ for usage examples."
    }
  ]
}
```

## Safety  
URL Shortener API checks if the provided `URL` is safe with the help of [Google Safe Browsing](https://safebrowsing.google.com/). In the case of unsafe URL, the API will respond with the original URL and message that indicates why the URL is not safe.

For example:

```html
https://www.shareaholic.com/v2/share/shorten_link?apikey=8943b7fd64cd8b1770ff5affa9a9437b&url=http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/&service[name]=shrlc
```

Response:

```json
{
  "errors": [
    {
      "code": "145",
      "source": {
        "pointer": "/data/attributes/short-url"
      },
      "detail": "Unsafe URL: Malware (Any platform)"
    }
  ]
}
```

## Error codes  
| Code | Description |
| --- | --- |
| 100 | `apikey` not provided |
| 101 | `apikey` provided is invalid |
| 140 | Missing `URL` |
| 141 | Invalid `URL` |
| 145 | URL shortening problem or unsafe `URL` |
| 429 | `rate_limit_exceeded` |

## Rate Limits  
In order to maintain an efficient, secure, and high-performing API, there are limits on how many times this API can be called in any given period. If you exceed your per-hour or per-minute call limit, you will receive a `rate_limit_exceeded` 429 error. To increase your limit, subscribe to a higher plan or contact your account manager for assistance. API responses include `X-RateLimit-*` headers that describe rate limit usage.

## Feedback  
If you believe you have found a bug, or you’d like to request additional functionality, or you release something using this API, we’d love to [hear from you](/content/contact/index.html).

Build with Shareaholic

Developer Tools and APIs that are reliable, stable, and fast. Built and run on the same scaled cloud infrastructure that runs Shareaholic products and powers functionality across over 300,000+ sites. Over 10 rock solid years in production.