Rebrandly for Developers

Use our API to create, track and share custom short links that incorporate your brand domain name.

Get Started

Creating a new link

Branded short links can be created via:

  • a POST HTTP request to https://api.rebrandly.com/v1/links, with JSON body defining the Link
  • a GET HTTP request to https://api.rebrandly.com/v1/links/new, with query parameters defining the Link

See in API explorer

Link Parameters

Table below shows the parameters you should specify when creating a Link:

Link property
Type
Constraints
Description

destination

string

required
UTF8
Valid URL
Max 1000 chars

The destination URL you want your branded short link to point to

slashtag

string

optional
Allowed character set:
A-Z, a-z, 0-9, _, -
Min 1 chars
Max 40 chars

The keyword portion of your branded short link. If not specified, will be autogenerated.

title

string

optional
UTF8
Min 3 chars
Max 255 chars

A title you assign to the branded short link in order to remember what's behind it

domain

object

optional
Domain Reference

A reference to the branded domain resource for this branded short link.
If not set, http://rebrand.ly is used

description

string

optional
Min 3 chars
Max 2000 chars

Available only if your plan includes link notes

A description/note you associate to the branded short link

Check for compatibility first

Double check whether your API key or OAuth token is enabled to use the Link Notes feature before sending a description field along with your Link object.
For every account, you can check for features and limits with a preliminary API call.

Examples of valid Link object to POST:

{
  "title": "What is Rebrandly",
  "slashtag": "video",
	"destination": "https://www.youtube.com/watch?v=3VmtibKpmXI"
}
{
  "title": "10 Books",
  "slashtag": "Books",
	"destination": "https://www.linkedin.com/pulse/10-books-every-founder-should-read-davide-de-guz",
  "domain": {
    "id": "4d20ec31db1e48c5aded19e93f137a11" 
  }
}
{
	"destination": "https://www.linkedin.com/pulse/10-books-every-founder-should-read-davide-de-guz",
}

Creating a new Link

$ curl 'https://api.rebrandly.com/v1/links' \
-X POST \
-H 'apikey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d \
'{
  "title": "What is Rebrandly",
  "slashtag": "video",
  "destination": "https://www.youtube.com/watch?v=3VmtibKpmXI"
}'
// slashtag and title are optional
$ curl 'https://api.rebrandly.com/v1/links/new?apikey=YOUR_API_KEY&destination=https://www.youtube.com/watch?v=3VmtibKpmXI&slashtag=video&domain\[id\]=8f104cc5b6ee4a4ba7897b06ac2ddcfb'
// slashtag and title are optional

JSON Response (just created link)

{
  "id": "fffa4cc5b6ee45d6g7897b06ac2d16af",
  "title": "What is Rebrandly",
  "slashtag": "video",
  "destination": "https://www.youtube.com/watch?v=3VmtibKpmXI",
  "createdAt": "2016-07-13T10:54:12.000Z",
  "updatedAt": "2016-07-13T10:54:12.000Z",
  "shortUrl": "rebrand.ly/video",
  "domain": {
    "id": "8f104cc5b6ee4a4ba7897b06ac2ddcfb",
    "ref": "/domains/8f104cc5b6ee4a4ba7897b06ac2ddcfb"
  }
}

Handling errors

HTTP Status
Error type
Description

403

Given pair of slashtag and domain forms a branded short link which already exists. Either change the domain or the slashtag.

403

Invalid Link object. Double check value for property field. Details about validation failure in message field.

Creating a new link


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.