Creating a new link

Branded short links can be created via:

  • a POST HTTP request to, with JSON body defining the Link
  • a GET HTTP request to, 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 propertyTypeConstraintsDescription
Valid URL
Max 2048 chars
The destination URL you want your branded short link to point to
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).
Min 3 chars
Max 255 chars
A title you assign to the branded short link in order to remember what's behind it
Domain Reference
A reference to the branded domain resource for this branded short link.
If not set, is used
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": ""
  "title": "10 Books",
  "slashtag": "Books",
	"destination": "",
  "domain": {
    "id": "4d20ec31db1e48c5aded19e93f137a11" 
	"destination": "",
Creating a new Link
$ curl '' \
-H 'apikey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d \
  "title": "What is Rebrandly",
  "slashtag": "video",
  "destination": ""
// slashtag and title are optional
$ curl '\[id\]=8f104cc5b6ee4a4ba7897b06ac2ddcfb'
// slashtag and title are optional
JSON Response (just created link)
  "id": "fffa4cc5b6ee45d6g7897b06ac2d16af",
  "title": "What is Rebrandly",
  "slashtag": "video",
  "destination": "",
  "createdAt": "2016-07-13T10:54:12.000Z",
  "updatedAt": "2016-07-13T10:54:12.000Z",
  "shortUrl": "",
  "domain": {
    "id": "8f104cc5b6ee4a4ba7897b06ac2ddcfb",
    "ref": "/domains/8f104cc5b6ee4a4ba7897b06ac2ddcfb"

Handling errors

HTTP StatusError typeDescription
403403 - Already existsGiven pair of slashtag and domain forms a branded short link which already exists. Either change the domain or the slashtag.
403403 - Invalid formatInvalid Link object. Double check value for property field. Details about validation failure in message field.