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 2048 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 (see notes below).

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.

Auto-generation strategy for slashtags

When the slashtag property is omitted in a Link creation request, the Rebrandly API automatically generates and associates it a random alphanumeric slashtag, which will be exposed in the Link creation response, as usual.

In order to provide a comprehensive view over the auto-generation strategy that Rebrandly adopts, the following commitments are exposed:

  • generated slashtags are no shorter than 3 characters and generally no longer than 8 characters
  • generated slashtags are the shortest possible for the specific Branded Domain in use.
  • any slashtag which recalls a profanity (bad words) is automatically excluded by the system so that no branded link will match unexpected meanings and potentially damage the brand's reputation
  • in order to always guarantee the same level of performances in Link creation, the Rebrandly API commits at generating up to 10% of the total slashtags available for the different lengths, given a branded domain of choice:
    • the first (1) 4,500 links will have a 3-chars long slashtag
    • the next (2) 160,000 links will have a 4-chars long slashtag
    • the next (2) 6,000,000 links will have a 5-chars long slashtag
    • then, you can assume the next 200 million links will have a 6-chars long slashtag, and the next 7 billions will have a 7-chars long one, etc.
  • chances are that slashtags which become free-to-use back in result to a Link deletion or a Link expire could be re-used by the system for a new link. If this is a problem to your use-case, please consider taking control over the slashtag generation strategy on the client side.

Formula is: [10% of] 36 (alphabet size) elevated to the Nth power (where N is the candidate slashtag's length)

(1) assuming no links have been created before; in case you have created links using the Dashboard or using the API specifying specific slashtags along with the request, this number decreases accordingly, taking into account for the 10% commitment the slashtags you have already consumed over time.
(2) same considerations as for (1) apply: if you used to create links with slashtags longer than 3/4/5/6/7/ characters, they will be taken into account for the 10% commitment.

📘

A word about slashtag generation commitment

If you need to alter your slashtag's minimum length for a given Branded Domain, the Rebrandly team can accomodate your request instructing the system to honor the minimum length preference. Note: this cannot be done at Account level or Workspace level, as the generation strategy is bounded to a specific branded domain.

If you find the generation strategy does not fit your use-case, please contact Rebrandly to discuss it.

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

403 - Already exists

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

403

403 - Invalid format

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

Updated about a month ago


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.