> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dashlink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom back halves

> Choose the path after your domain instead of taking a generated one.

The back half is everything after the domain:

```
https://go.example.com/spring-sale
                       ^^^^^^^^^^^
```

Omit `back_half` and one is generated. Supply it and the link reads as something a person would trust and could retype.

```bash cURL theme={null}
curl -X POST "https://api.dashlink.ai/api/v1/shortlinks/create_shortlink" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -F "destination_url=https://example.com/q2-earnings-report-final.pdf" \
  -F "back_half=q2-earnings"
```

```javascript Node.js theme={null}
const body = new FormData();
body.append("destination_url", "https://example.com/q2-earnings-report-final.pdf");
body.append("back_half", "q2-earnings");

const response = await fetch("https://api.dashlink.ai/api/v1/shortlinks/create_shortlink", {
  method: "POST",
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
  body,
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.dashlink.ai/api/v1/shortlinks/create_shortlink',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
    data={
        'destination_url': 'https://example.com/q2-earnings-report-final.pdf',
        'back_half': 'q2-earnings',
    },
)
payload = response.json()
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"net/url"
	"strings"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/shortlinks/create_shortlink"
	form0 := url.Values{
		"destination_url": {"https://example.com/q2-earnings-report-final.pdf"},
		"back_half": {"q2-earnings"},
	}
	req0, err0 := http.NewRequest("POST", endpoint0, strings.NewReader(form0.Encode()))
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/shortlinks/create_shortlink")
request0 = Net::HTTP::Post.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
request0.set_form_data("destination_url" => "https://example.com/q2-earnings-report-final.pdf", "back_half" => "q2-earnings")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/shortlinks/create_shortlink');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
curl_setopt($ch0, CURLOPT_POSTFIELDS, http_build_query(['destination_url' => 'https://example.com/q2-earnings-report-final.pdf', 'back_half' => 'q2-earnings']));
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

## Rules

* Letters, numbers, hyphens and underscores
* Unique **per domain** — `go.example.com/sale` and `links.example.com/sale` can coexist
* Case-sensitive
* Some words are reserved for platform use

A back half already taken on that domain returns `409`:

```json theme={null}
{
  "error": {
    "message": "This back-half is already in use on that domain.",
    "status_code": 409,
    "code": "DUPLICATE_ENTRY"
  }
}
```

## Handling collisions

Treat `409` as a signal to pick another value rather than as an error to surface:

```python theme={null}
import itertools

def create_with_fallback(destination_url, preferred_back_half, **fields):
    for suffix in itertools.chain([""], (f"-{n}" for n in range(2, 12))):
        response = requests.post(
            f"{BASE}/shortlinks/create_shortlink",
            headers=HEADERS,
            data={
                "destination_url": destination_url,
                "back_half": preferred_back_half + suffix,
                **fields,
            },
        )
        payload = response.json()

        if "data" in payload:
            return payload["data"]

        # Anything other than a collision is a real problem and retrying
        # a different back half will not fix it.
        if payload["error"].get("code") != "DUPLICATE_ENTRY":
            raise RuntimeError(payload["error"]["message"])

    raise RuntimeError(f"No variation of {preferred_back_half!r} was free")
```

## Choosing good ones

> [accordion] Short enough to say out loud
>
> A back half that appears on a slide or in a podcast gets typed by hand. `/q2-earnings` survives that; `/q2-earnings-report-final-v3` does not.

> [accordion] Avoid ambiguous characters
>
> `0` and `O`, `1` and `l`. Anywhere the link might be read from print or a screen, these cost you visitors.

> [accordion] Stable, not descriptive of the destination
>
> `/pricing` survives a pricing page being restructured. `/pricing-2026-q1-v2` describes a URL that will change, and you cannot fix it after the link is shared.

> [accordion] Prefix by channel when you will compare them
>
> `/spring-email`, `/spring-social`, `/spring-print` give separate analytics per channel without needing UTM parameters to tell them apart.

## Changing one later

`update_shortlink` accepts `back_half`:

```bash cURL theme={null}
curl -X POST "https://api.dashlink.ai/api/v1/shortlinks/update_shortlink" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -F "name=SHORT-0001" \
  -F "back_half=spring-sale-2026"
```

```javascript Node.js theme={null}
const body = new FormData();
body.append("name", "SHORT-0001");
body.append("back_half", "spring-sale-2026");

const response = await fetch("https://api.dashlink.ai/api/v1/shortlinks/update_shortlink", {
  method: "POST",
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
  body,
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.dashlink.ai/api/v1/shortlinks/update_shortlink',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
    data={
        'name': 'SHORT-0001',
        'back_half': 'spring-sale-2026',
    },
)
payload = response.json()
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"net/url"
	"strings"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/shortlinks/update_shortlink"
	form0 := url.Values{
		"name": {"SHORT-0001"},
		"back_half": {"spring-sale-2026"},
	}
	req0, err0 := http.NewRequest("POST", endpoint0, strings.NewReader(form0.Encode()))
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/shortlinks/update_shortlink")
request0 = Net::HTTP::Post.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
request0.set_form_data("name" => "SHORT-0001", "back_half" => "spring-sale-2026")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/shortlinks/update_shortlink');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
curl_setopt($ch0, CURLOPT_POSTFIELDS, http_build_query(['name' => 'SHORT-0001', 'back_half' => 'spring-sale-2026']));
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

> [!WARNING]
>
> The old back half stops working immediately and is freed for reuse. Anyone holding the old link gets a dead link. Analytics stay with the record, so history is not lost — but the link is.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.