> ## 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.

# Migrating from another shortener

> Moving existing links across without breaking the ones already in circulation.

The hard part of a migration is not creating links — it is that links already printed, emailed and posted cannot be changed. Plan around what you cannot move.

## What can and cannot come with you

| | Moves? |
| - | - |
| Destination URLs | Yes |
| Back-halves | Yes, if free on your domain |
| Tags and grouping | Yes, recreate as [tags](https://docs.dashlink.ai/guides/links/tags.md) and [campaigns](https://docs.dashlink.ai/guides/campaigns/introduction.md) |
| Your custom domain | Yes — but it points at one provider at a time |
| Historical click data | No. Export it from the old provider before you finish |
| Links on the old provider's shared domain | No. A path on a domain you do not control cannot move with you |

> [!WARNING]
>
> Export your historical analytics from the old provider first, while you still have access. It does not transfer, and it is not recoverable once the account closes.

## The domain question

This is what determines your sequencing.

If your links are on **the old provider's domain**, they cannot follow you. Keep that account alive as long as those links matter, and use new links from now on.

If they are on **your own custom domain**, they can — but DNS points at one provider at a time, so every existing back-half must exist here before you switch, or they break at the moment of cutover.

**1. Export everything from the old provider**

Back-half and destination at minimum. Tags and groups if you can get them.

**2. Add the domain here, but do not point DNS at us yet**

Complete [verification](https://docs.dashlink.ai/guides/branded-links/custom-domains.md). Serving continues from the old provider throughout.

**3. Recreate every link with its exact back-half**

Same back-half, same destination. This is the step that must be complete.

**4. Reconcile**

Compare the full list here against your export. Every back-half must be present and pointing at the right place.

**5. Switch DNS**

Traffic moves to us as DNS propagates. Because the back-halves match, in-flight links keep resolving.

**6. Watch for 404s**

A back-half that was missed shows up as a not-found. Create it immediately — the link is already out in the world.

## Importing

```bash cURL theme={null}
# CSV columns: back_half,destination_url,title
while IFS=, read -r back_half destination_url title; do
  curl -sS -X POST https://api.dashlink.ai/api/v1/shortlinks/create_shortlink \
    -H "X-API-Key: $DASHLINK_API_KEY" \
    -F "destination_url=$destination_url" \
    -F "domain=$DOMAIN" \
    -F "back_half=$back_half" \
    -F "title=$title"
done < links.csv
```

```javascript Node.js theme={null}
import { createReadStream } from "node:fs";
import { parse } from "csv-parse";

async function importLinks(client, csvPath, domain) {
  const failures = [];
  const rows = createReadStream(csvPath).pipe(parse({ columns: true }));

  for await (const row of rows) {
    const body = new FormData();
    body.append("destination_url", row.destination_url);
    body.append("domain", domain);
    body.append("back_half", row.back_half);
    body.append("title", row.title ?? "");

    try {
      await client.call("POST", "shortlinks/create_shortlink", { body });
    } catch (error) {
      failures.push([row.back_half, error.code, error.message]);
    }
  }

  return failures;
}
```

```python Python theme={null}
import csv, json, time

def import_links(client, csv_path, domain):
    failures = []

    with open(csv_path) as handle:
        for row in csv.DictReader(handle):
            fields = {
                "destination_url": (None, row["destination_url"]),
                "domain": (None, domain),
                "back_half": (None, row["back_half"]),
                "title": (None, row.get("title", "")),
            }
            try:
                client.call("POST", "shortlinks/create_shortlink", files=fields)
            except DashlinkError as error:
                failures.append((row["back_half"], error.code, error.message))

    return failures
```

```go Go theme={null}
type failure struct {
	BackHalf string
	Code     string
	Message  string
}

func ImportLinks(c *Client, csvPath, domain string) ([]failure, error) {
	handle, err := os.Open(csvPath)
	if err != nil {
		return nil, err
	}
	defer handle.Close()

	rows, err := csv.NewReader(handle).ReadAll()
	if err != nil {
		return nil, err
	}

	header, rows := rows[0], rows[1:]
	index := map[string]int{}
	for i, name := range header {
		index[name] = i
	}

	var failures []failure

	for _, row := range rows {
		body := &bytes.Buffer{}
		form := multipart.NewWriter(body)
		form.WriteField("destination_url", row[index["destination_url"]])
		form.WriteField("domain", domain)
		form.WriteField("back_half", row[index["back_half"]])
		form.WriteField("title", row[index["title"]])
		form.Close()

		if _, err := c.Call("POST", "shortlinks/create_shortlink", body); err != nil {
			var apiErr *Error
			if errors.As(err, &apiErr) {
				failures = append(failures, failure{
					BackHalf: row[index["back_half"]],
					Code:     apiErr.Code,
					Message:  apiErr.Message,
				})
				continue
			}
			return failures, err
		}
	}

	return failures, nil
}
```

```ruby Ruby theme={null}
require "csv"

def import_links(client, csv_path, domain)
  failures = []

  CSV.foreach(csv_path, headers: true) do |row|
    begin
      client.call("POST", "shortlinks/create_shortlink",
                  destination_url: row["destination_url"],
                  domain: domain,
                  back_half: row["back_half"],
                  title: row["title"].to_s)
    rescue DashlinkError => error
      failures << [row["back_half"], error.code, error.message]
    end
  end

  failures
end
```

```php PHP theme={null}
<?php
function import_links(Dashlink $client, string $csvPath, string $domain): array
{
    $failures = [];
    $handle = fopen($csvPath, 'r');
    $header = fgetcsv($handle);

    while (($values = fgetcsv($handle)) !== false) {
        $row = array_combine($header, $values);

        try {
            $client->call('POST', 'shortlinks/create_shortlink', [
                'destination_url' => $row['destination_url'],
                'domain' => $domain,
                'back_half' => $row['back_half'],
                'title' => $row['title'] ?? '',
            ]);
        } catch (DashlinkError $error) {
            $failures[] = [$row['back_half'], $error->errorCode, $error->getMessage()];
        }
    }

    fclose($handle);

    return $failures;
}
```

Pace it. A few thousand links at full speed will hit your rate limit; see [Working within rate limits](https://docs.dashlink.ai/guides/patterns/rate-limits.md).

> [!NOTE]
>
> `create_shortlink` is multipart, which is why fields are passed as `files` rather than `data`. See [Creating links](https://docs.dashlink.ai/guides/links/create.md).

## Reconciling before cutover

```python theme={null}
def missing_back_halves(client, expected, domain):
    present = {
        link["back_half"]
        for link in iter_links(client, domain=domain)
    }
    return sorted(set(expected) - present)
```

Run it until it returns nothing. Do not switch DNS on a partial import — every missing back-half is a dead link the moment traffic moves.

## Handling failures

> [accordion] DUPLICATE\_ENTRY
>
> That back-half already exists on this domain. Usually a re-run of a partially completed import; verify the existing link points where it should before treating it as done.

> [accordion] INVALID\_PARAMETER on back\_half
>
> The other provider allowed a character we do not, or the length differs. These need a decision per link, and the old link will break at cutover — a redirect from the old system, if it offers one, is the only way to preserve it.

> [accordion] FEATURE\_LIMIT\_EXCEEDED
>
> Your plan's link allowance is exhausted. Check `get_feature_limits` against your export size before starting, not halfway through.

## After the switch

Keep the old account open for a while. It is your evidence when someone asks what a link used to point at, and your fallback if the cutover surfaces something the reconciliation missed. Close it once traffic to the old provider has gone quiet and you have your historical export safely stored.


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