Overview

The App API lets you view and update an existing Branch app configuration.

Before you begin

To access the App API, you first need to:

1. Create a Branch account.

Authentication

For calls to the App API, you need your Branch Key and Branch Secret.

Legacy Branch

To retrieve your credentials in the legacy Branch experience:

1. Navigate to the Account → Settings → Profile tab.
2. Use the copy icons to copy your Branch Key and Branch Secret.

New Branch

To retrieve your credentials in the new Branch experience:

1. Navigate to the Configuration → Security & Access → Credentials tab.
2. Use the copy icons to copy your Branch Key and Branch Secret.

Visit our guide to learn more about managing your Branch credentials.

API usage

Get current Branch app config

Endpoint

GET /v1/app/{branch_key}?branch_secret={branch_secret}
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request parameters

Parameter	Description	Required
branch_key	The Branch Key of the originating app; from your Branch Settings Dashboard	Yes
branch_secret	The Branch Secret of the originating app; from your Branch Settings Dashboard	Yes

Example request/response

Example Request (cURL)

curl GET 'https://api2.branch.io/v1/app/{branch_key}?branch_secret={branch_secret}'

Example Response (JSON)

{
  branch_key: "the app key",
  branch_secret: "the app secret",
  creation_date : "date app was created",

  app_name: "name of the app",

  dev_name: "main contact name",
  dev_email: "main contact email",
  dev_phone_number: "main contact phone",

  android_app: "whether an Android app is enabled",
  android_url: "url of Android store, or namespace (com.android.myapp)",
  android_uri_scheme: "the Android URI scheme",
  android_package_name: "the Android package name",
  sha256_cert_fingerprints: "the SHA256 fingerprints for App Links",
  android_app_links_enabled: "whether App Links are enabled",

  ios_app: "whether an iOS app is enabled",
  ios_url: "url of iOS store, or app id (id512451233)",
  ios_uri_scheme: "the iOS URI scheme",
  ios_store_country: "the country code of the app, default to US",
  ios_bundle_id: "the iOS bundle ID",
  ios_team_id: "the iOS Team ID",
  universal_linking_enabled: "whether Universal Links are enabled",

  fire_url: "the redirect on Fire phones",
  windows_phone_url: "the redirect on Windows phones",
  blackberry_url: "The redirect on Blackberry phones",
  web_url: "backup website if URLs are null",
  default_desktop_url: "the default desktop redirect, or null if set to hosted SMS",

  short_url_domain: "white labeled domain for short links",

  text_message: "text message to use, {{ link }} will be replaced with short link",

  og_app_id: "optional default Open Graph (OG) app id",
  og_title: "optional default OG title",
  og_image_url: "optional default OG image URL",
  og_description: "optional default OG description",

  deepview_desktop: "the current deepview selected for the desktop platform",
  deepview_ios: "the current deepview selected for the iOS platform",
  deepview_android: "the current deepview selected for the Android platform",
}

Update Branch app config

Endpoint

PUT /v1/app/{branch_key}
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request parameters

Parameter	Description	Required
branch_secret	The Branch Secret of the originating app; from your Branch Settings Dashboard	Yes
app_name	The name of the app (max 255 characters).	No
dev_name	The main contact developer name (max 255 characters).	No
dev_email	The main contact developer email (max 255 characters).	Yes
android_url	The URL of the Android store, or package name (com.android.myapp). Note that to set a fallback URL for Android instead, you must also set android_app to 2.	No
android_uri_scheme	The Android URI scheme.	No
ios_url	The URL of the iOS store, or app ID (id512451233).	No
ios_uri_scheme	The iOS URI scheme.	No
ios_store_country	The country code of the app, which defaults to US (max 255 characters).	No
web_url	Backup website if URLs are null.	No
text_message	The text message to use for the text-me feature, where {{ link }} is replaced with the short link (max 255 characters).	No
og_app_id	Default Open Graph (OG) app ID (max 255 characters).	No
og_title	Default OG title to be used with links (max 255 characters).	No
og_description	Default OG description to be used with links (max 255 characters).	No
og_image_url	Default OG image URL to be used with links (max 255 characters).	No

Example request/response

Example Request (cURL)

curl --request PUT \
                    --url 'https://api2.branch.io/v1/app/key_live_XXXX' \
                    --header 'Accept: application/json' \
                    --header 'Content-Type: application/json' \
                    --data '
                    {
                    "branch_secret": "secret_live_XXXX",
                    "dev_email": "dev@example.com",
                    "og_title": "New App Title"
                    }
                    '

Example Response (JSON)

{
  branch_key: "the app key",
  branch_secret: "the app secret",
  creation_date : "date app was created",

  app_name: "name of the app",

  dev_name: "main contact name",
  dev_email: "main contact email",
  dev_phone_number: "main contact phone",

  android_url: "url of Android store, or namespace (com.android.myapp)",
  android_uri_scheme: "the Android URI scheme",

  ios_url: "url of iOS store, or app id (id512451233)",
  ios_uri_scheme: "the iOS URI scheme",
  ios_store_country: "the country code of the app, default to US",

  web_url: "backup website if URLs are null",

  short_url_domain: "white labeled domain for short links",

  text_message: "text message to use, {{ link }} will be replaced with short link",

  og_app_id: "optional default Open Graph (OG) app id",
  og_title: "optional default OG title",
  og_image_url: "optional default OG image URL",
  og_description: "optional default OG description"
}