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:

🚧

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",
}

$ 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

{
  "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