Creating a new Campaign link

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 to https://enteprise-api.rebrandly.com/v1/links, with JSON body defining an array of Link

See in API explorer

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

JSON Response (just created link)

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