Migrate from Branch

Before you start#

• The import is in the dashboard under Links > Import links and on the REST API as POST /v1/links/import (Business and Enterprise).
• Every plan can import within its link limit: Free 4, Pro 10, Business 500, Enterprise without a limit. Custom paths and deep links need Pro, custom domains need Business.
• One file holds up to 1000 links and 2 MB in the dashboard, or 480 KB per API request.

1. Export your links from Branch#

Branch has no single file with every link and every setting. Use the export that matches how your links were made, or combine them in one CSV.

This script reads every link in links.txt (one URL per line) and writes a CSV with a url column and the full API response in a data column, which the import reads as is.

export BRANCH_KEY="key_live_..."
printf 'url,data\n' > branch-links.csv
while IFS= read -r link; do
  data=$(curl -s --get "https://api2.branch.io/v1/url" \
    --data-urlencode "url=$link" \
    --data-urlencode "branch_key=$BRANCH_KEY")
  printf '%s,"%s"\n' "$link" "$(printf '%s' "$data" | sed 's/"/""/g')" >> branch-links.csv
done < links.txt

Any CSV works as long as it has a header row. Columns named after Branch keys ($ios_url, ~campaign), a url or Short link column, an alias column, a data JSON column and the display names of Branch’s web-link bulk file (Link Title, Original Web URL, Link Alias) are all read. Comma, semicolon and tab separators are detected automatically.

2. What carries over#

Not carried over#

The report lists every key that does not move, for every link, so nothing disappears without a note. The most common ones:

• Other preview tags, such as $og_type, $og_video and the $twitter_* tags.
• Deepviews and behaviour keys: $ios_passive_deepview, $android_passive_deepview, $desktop_deepview, $web_only, $after_click_url, $ios_redirect_timeout, $uri_redirect_mode, $always_deeplink.
• Other platforms and variants: $windows_phone_url, $blackberry_url, $fire_url, $ios_wechat_url, $android_wechat_url, and the country variants such as $ios_url_xx. Appy has country rules for Android instead.
• Extra labels: ~tags, ~stage, ~campaign_id, ~secondary_publisher, ~ad_set_name, $3p.
• Custom data keys that your app reads through the Branch SDK, such as product_id. Put what the app needs into the deep link instead, for example acme://product/42.
• Keys Branch generates, such as ~id, ~creation_source and +url, are listed as ignored.
• Click history stays in Branch. Appy counts clicks from the moment a link is imported.

3. Run the import#

1. 1

   Upload

   Open Links > Import links, choose Branch and add the CSV. Under Defaults, fill in what your links leave out: the website, the App Store and Google Play pages, your app’s URI scheme and, for files without full links, the old link domain. Branch sets the App Store and Google Play pages once in Link Settings, so exports often leave them out. Rows that set their own value keep it.

2. 2

   Preview

   See which column went where, which keys are not carried over and which domains the links use, with what each domain needs to keep working.

3. 3

   Check

   Every link is validated without writing anything: the path rules, every URL, the domain blocklist and your plan’s link limit. Each link shows its new address, where each device goes and a note for anything that changes. Download the report to share it or to plan reprints.

4. 4

   Import

   The links that are ready are created in file order until your plan’s link limit is reached; the rest are reported as over the limit. Run the same file again after fixing a row: links already in your account are skipped.

4. Keep printed links working#

The alias becomes the Appy path when it fits Appy’s rules: 5 to 64 characters, letters, numbers and dashes, not reserved and not already used by another Appy account. Appy paths are not case-sensitive, so /Spring-Sale and /spring-sale open the same link. Links without an alias, like acme.app.link/WgiqvsepqF, keep their generated ID as the path when it fits too.

5. Move the SDK separately#

Importing links does not touch your app. Links route by device and open the app through the deep link on every paid plan without any SDK. Universal Links and App Links on go.acme.com follow the domain: once its DNS points to Appy, iOS and Android read the association files from Appy, so set them up before the switch.

• On Enterprise, register the app under Apps & SDK and assign the domain to it, so Appy serves apple-app-site-association and assetlinks.json on go.acme.com (app links on your domain).
• Replace the Branch SDK calls with the Appy SDK for iOS or Android, or use two HTTP calls from React Native, Flutter or Unity. Values your app read from Branch link data now come from the deep link URL.
• Ship the app update before or together with the DNS change, so new installs and returning users land in the app.

Import with the API#

Send the file’s contents as csv. Run with "dryRun": true first: the response is the same report the dashboard shows and nothing is written. Send the same request with "dryRun": false to create the ready links. The API reference has the full schema.

curl https://api.appy.to/v1/links/import \
  -H "Authorization: Bearer $APPY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "branch",
    "dryRun": true,
    "csv": "url,$fallback_url,$ios_url,$android_url,~campaign\nhttps://go.acme.com/spring,https://acme.com/spring,https://apps.apple.com/app/id123456789,https://play.google.com/store/apps/details?id=com.acme.shop,spring\n",
    "defaults": {"deeplinkScheme": "acme://"}
  }'

{
  "dryRun": true,
  "source": "branch",
  "plan": "business",
  "limit": 500,
  "used": 37,
  "summary": {
    "rows": 1,
    "ready": 1,
    "imported": 0,
    "existing": 0,
    "errors": 0,
    "overLimit": 0,
    "aliasesKept": 1,
    "aliasesChanged": 0,
    "withWarnings": 0
  },
  "domains": [
    {
      "host": "go.acme.com",
      "kind": "branded",
      "rows": 1,
      "appyStatus": "not_added"
    }
  ],
  "rows": [
    {
      "line": 2,
      "status": "ready",
      "alias": "spring",
      "slug": "spring",
      "aliasKept": true,
      "fallbackUrl": "https://acme.com/spring?utm_campaign=spring",
      "targets": {
        "iphone": "https://apps.apple.com/app/id123456789",
        "android": "https://play.google.com/store/apps/details?id=com.acme.shop"
      },
      "unsupported": [],
      "ignored": [],
      "issues": []
    }
  ]
}

• status is ready (dry run only), imported, exists, error or over_limit.
• aliasKept is true when the old path equals the new one, so the old URL works once its domain points to Appy.
• issues carry a stable code, a severity and an English message; unsupported and ignored list the keys of that row that did not move.
• Rate limits and errors are the same as for the other link endpoints.

Limits#

• app.link, test-app.link and bnc.lt links cannot move; only branded domains can.
• One deep link per link; per-platform deep link paths that differ keep the iOS one.
• No Deepviews, Windows, BlackBerry, Fire OS or WeChat routes.
• Up to 1000 links per file. Larger exports go in several files; links already imported are skipped, so files can overlap.
• Imports count toward your plan’s link limit like any other link; rows that do not fit are reported, not dropped.
• Moving the SDK, analytics history and Branch integrations is a separate step.