Creating a new Campaign link
To meet customer needs for faster link creation and overcome the 10/second API call limit of standard Rebrandly plans, our API model allows developers to implement special flows in their scripts to match high availability and performance requirements and access an extended feature set.
A Campaign link can only be created inside a Campaign (formerly Extended) Workspace.
What's new in a Campaign Workspace
Improved link creation rate
Evergreen Workspaces has an important limitation regarding the number of links you can create per second. Currently, you can create no more than 10 links per second in a Rebrandly Evergreen Workspace, which is likely to become limiting for your use case if:
- Your client application is running in a distributed environment, or
- You plan to import many links as part of a batch operation.
To overcome Evergreen Workspaces’ rate limiting issue for distributed environments (1), Campaign Workspaces allows client applications to create links via HTTP PUT /v1/links
at a rate that is much higher than 10 created links per second, allowing clients to send up to 25 link creation requests in one single API call to the /v1/links endpoint.
The default API rate limit for PUT method is 1 request per second. If you need a higher rate, you can reach Rebrandly through the support.
Auto-expire/TTL
The link auto-expiry feature is available in all Campaign Workspaces. API users will be provided with specific maximum and minimum TTL info they can set for links created by the Rebrandly team.
Link auto-expiry is not optional in Campaign Workspaces, and the maximum default value is 90 days.
API Only
Links created in a Campaign Workspace can only be created via API. Campaign links cannot be listed. You can access them only directly through their identification number.
Link Parameters
Branded short links can be created via:
- a
PUT
HTTP request tohttps://enteprise-api.rebrandly.com/v1/links
, with JSON body defining an array of Link
Workspace field in the header is mandatory.
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). |
domain | object | optional Domain Reference | A reference to the branded domain resource for this branded short link. |
tags | array | optional Tags Reference | A list of tags ids to attach to the link |
scripts | array | optional Retargeting Scripts Reference | A list of retargeting scripts ids to attach to the link |
ttl | integer | optional Min 3600 | Time to live of the link expressed in seconds |
Examples of valid Link object to PUT:
$ curl 'https://api.rebrandly.com/v1/links' \
-X POST \
-H 'apikey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'worlspace: CAMPAIGN_WORKSPACE_ID' \
-d \
'[{
"slashtag": "video",
"destination": "https://www.youtube.com/watch?v=3VmtibKpmXI",
"domain": {"id": YOUR_DOMAIN_ID}
}]'
// slashtag and title are optional
[{
"id": "fffa4cc5b6ee45d6g7897b06ac2d16af",
"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 26 days ago