Creating a new link
Branded short links can be created via:
- a
POST
HTTP request tohttps://api.rebrandly.com/v1/links
, with JSON body defining the Link - a
GET
HTTP request tohttps://api.rebrandly.com/v1/links/new
, with query parameters defining the Link
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",
}
$ 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
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 6 months ago