API

Postman

  • Use Postman to test Branch API for requests, responses, and code examples

  • Change the branch_key to match your Branch Dashboard

  • Run in Postman

    • Request

      curl -XPOST https://api.branch.io/v1/url \
        -d '{
        "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
        "channel": "facebook",
        "feature": "onboarding",
        "campaign": "new product",
        "stage": "new user",
        "tags": ["one", "two", "three"],
        "data": {
          "$canonical_identifier": "content/123",
          "$og_title": "Title from Deep Link",
          "$og_description": "Description from Deep Link",
          "$og_image_url": "http://www.lorempixel.com/400/400/",
          "$desktop_url": "http://www.example.com",
          "custom_boolean": true,
          "custom_integer": 1243,
          "custom_string": "everything",
          "custom_array": [1,2,3,4,5,6],
          "custom_object": { "random": "dictionary" }
        }
      }'
      
    • Response

      {
        "url": "https://example.app.link/WgiqvsepqF"
      }
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      ... ... Parameters from Configuring Links
    • Request

      curl -XPOST https://api.branch.io/v1/url/bulk/key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt \
        -d '[
          {
            "channel": "facebook",
            "feature": "onboarding",
            "campaign": "new product",
            "stage": "new user",
            "tags": ["one", "two", "three"],
            "data": {
              "$canonical_identifier": "content/123",
              "$og_title": "Title from Deep Link",
              "$og_description": "Description from Deep Link",
              "$og_image_url": "http://www.lorempixel.com/400/400/",
              "$desktop_url": "http://www.example.com",
              "custom_boolean": true,
              "custom_integer": 1243,
              "custom_string": "everything",
              "custom_array": [1,2,3,4,5,6],
              "custom_object": { "random": "dictionary" }
            }
          },
          {
            "channel": "facebook",
            "feature": "onboarding",
            "campaign": "new product",
            "stage": "new user",
            "tags": ["one", "two", "three"],
            "data": {
              "$canonical_identifier": "content/123",
              "$og_title": "Title from Deep Link",
              "$og_description": "Description from Deep Link",
              "$og_image_url": "http://www.lorempixel.com/400/400/",
              "$desktop_url": "http://www.example.com"
            }
          }
        ]'
      
    • Response

      [
        {
          "url": "https://example.app.link/0AjuiLcpqF"
        },
        {
          "url": "https://example.app.link/5IULiLcpqF"
        }
      ]
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      ... ... Parameters from Configuring Links
    • Returns deep link properties

    • Request

      curl -XGET 'https://api.branch.io/v1/url?url=https://example.app.link/WgiqvsepqF&branch_key=key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt'
      
    • Response

      {
        "campaign": "new product",
        "channel": "facebook",
        "feature": "onboarding",
        "stage": "new user",
        "tags": [
          "one",
          "two",
          "three"
        ],
        "data": {
          "$canonical_identifier": "content/123",
          "$desktop_url": "http://www.example.com",
          "$og_description": "Description from Deep Link",
          "$og_image_url": "http://www.lorempixel.com/400/400/",
          "$og_title": "Title from Deep Link",
          "$one_time_use": false,
          "custom_array": [
            1,
            2,
            3,
            4,
            5,
            6
          ],
          "custom_boolean": true,
          "custom_integer": 1243,
          "custom_object": {
            "random": "dictionary"
          },
          "custom_string": "everything",
          "~campaign": "new product",
          "~channel": "facebook",
          "~creation_source": 0,
          "~feature": "onboarding",
          "~id": "423196192848102356",
          "~stage": "new user",
          "~tags": [
            "one",
            "two",
            "three"
          ],
          "url": "https://example.app.link/WgiqvsepqF"
        },
        "type": 0,
        "alias": null
      }
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      url string The deep link url
    • Request

      curl -XPUT 'https://api.branch.io/v1/url?url=https%3A%2F%2Fexample.app.link%2F5IULiLcpqF' \
        -d '{
        "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
        "branch_secret": "secret_live_RrrsLqpzVcoVWf5t4ncQVpzlg2pRpGH9",
        "channel": "twitter",
        "data":{
          "name":"alex",
          "user_id":"12346",
        }
      }'
      
    • Response

      {
        "campaign": "new product",
        "channel": "twitter",
        "feature": "onboarding",
        "stage": "new user",
        "tags": [
          "one",
          "two",
          "three"
        ],
        "data": {
          "$one_time_use": false,
          "name": "alex",
          "user_id": "12346",
          "~campaign": "new product",
          "~channel": "twitter",
          "~creation_source": 0,
          "~feature": "onboarding",
          "~id": "423196096467215333",
          "~stage": "new user",
          "~tags": [
            "one",
            "two",
            "three"
          ],
          "url": "https://example.app.link/5IULiLcpqF"
        },
        "type": 0,
        "alias": null
      }
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      branch_secret string From your Branch Settings Dashboard
      url string The deep link url
    • data is overridden on Link update, not appended

    • Bulk link creator is limited to 1000 links at a time

Event

  • Event create

    • Request

      curl -XPOST https://api.branch.io/v1/event \
        -d '{
        "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
        "identity": "bob",
        "event": "custom_event",
        "metadata": {
          "custom_data": "anything",
          "hello": "world"
        }
      }'
      
    • Response

      {}
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      event string Name of the custom event
      identity string Unique user id, also known as the Developer Id on your Branch Identity Dashboard
      metadata {} Custom key-value pairs related to the event
  • Event create commerce

    • Request

      curl -X POST https://api.branch.io/v1/event \
        -d '{
        "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
        "identity": "222",
        "event": "purchase",
        "metadata": {
          "hello": "world",
          "custom_data": "this"
        },
        "commerce_data": {
          "revenue": 50.0,
          "currency": "USD",
          "transaction_id": "foo-transaction-id",
          "shipping": 0.0,
          "tax": 5.0,
          "affiliation": "foo-affiliation",
          "products": [
            {
              "sku": "foo-sku-1",
              "name": "foo-item-1",
              "price": 45.00,
              "quantity": 1,
              "brand": "foo-brand",
              "category": "Electronics",
              "variant": "foo-variant-1"
            },
            {
              "sku": "foo-sku-2",
              "price": 2.50,
              "quantity": 2
            }
          ]
        }
      }'
      
    • Response

      {}
      

User

  • User create

    • Request

      curl -XPOST https://api.branch.io/v1/profile \
        -d '{
          "branch_key":"key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
          "identity":"steve",
          "identity_id":"444"
      }'
      
    • Response

      {
        "identity_id": 444,
        "link": "https://example.app.link/?%24identity_id=444"
      }
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      identity string Unique user id, also known as the Developer Id on your Branch Identity Dashboard
      identity_id string Unique user id for Branch, also known as the Branch Identity Id on your Branch Identity Dashboard
  • User read

    • Request

      # identity
      curl -XGET 'https://api.branch.io/v1/profile?branch_key=key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt&identity=steve'
      
      # identity id
      curl -XGET 'https://api.branch.io/v1/profile?branch_key=key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt&identity_id=444'
      
    • Response

      {
        "identity_id": 444,
        "identity": "steve",
        "link": "https://example.app.link/?%24identity_id=444"
      }
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      identity string Unique user id, also known as the Developer Id on your Branch Identity Dashboard √*
      identity_id string Unique user id for Branch, also known as the Branch Identity Id on your Branch Identity Dashboard √*
      • * = identity OR identity_id is required

Referral

  • Referral reward

    • Request

      curl -XPOST https://api.branch.io/v1/credits \
        -d '{
        "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
        "branch_secret": "secret_live_RrrsLqpzVcoVWf5t4ncQVpzlg2pRpGH9",
        "identity": "steve",
        "amount": "10",
        "bucket": "default"
      }'
      
    • Response

      {
        "success": true
      }
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      branch_secret string From your Branch Settings Dashboard
      identity string Unique user id, also known as the Developer Id on your Branch Identity Dashboard
      amount string Number of credits
      bucket string The category where the credits are save to (defaults to default)
  • Referral redeem

    • Request

      curl -XPOST https://api.branch.io/v1/redeem \
        -d '{
        "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
        "branch_secret": "secret_live_RrrsLqpzVcoVWf5t4ncQVpzlg2pRpGH9",
        "identity": "steve",
        "amount": "5",
        "bucket": "default"
      }'
      
    • Response

      // success
      {}
      
      // failure
      {
        "error": {
          "code": 402,
          "message": "Not enough credits to redeem."
        }
      }
      
  • Referral read

    • Request

      curl -XGET 'https://api.branch.io/v1/credits?branch_key=key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt&identity=steve'
      
    • Response

      {
        "default": 40
      }
      
  • Referral history

    • Request

      curl -XGET 'https://api.branch.io/v1/credithistory?branch_key=key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt&identity=steve'
      
    • Response

      [
        {
          "transaction": {
            "date": "2017-08-07T22:15:10.503Z",
            "id": "423229952507361694",
            "bucket": "default",
            "type": 2,
            "amount": -5
          },
          "event": {
            "name": null,
            "metadata": null
          },
          "referrer": null,
          "referree": null
        },
        {
          "transaction": {
            "date": "2017-08-07T22:15:01.818Z",
            "id": "423229916080032437",
            "bucket": "default",
            "type": 2,
            "amount": -5
          },
          "event": {
            "name": null,
            "metadata": null
          },
          "referrer": null,
          "referree": null
        },
        {
          "transaction": {
            "date": "2017-08-07T22:10:57.224Z",
            "id": "423228890178439487",
            "bucket": "default",
            "type": 1,
            "amount": 10
          },
          "event": {
            "name": null,
            "metadata": null
          },
          "referrer": null,
          "referree": null
        },
        {
          "transaction": {
            "date": "2017-08-07T22:10:56.416Z",
            "id": "423228886789240847",
            "bucket": "default",
            "type": 1,
            "amount": 10
          },
          "event": {
            "name": null,
            "metadata": null
          },
          "referrer": null,
          "referree": null
        }
      ]
      
  • Referral reconcile

    • Request

      curl -X POST https://api.branch.io/v1/reconcile \
        -d '{
        "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
        "branch_secret": "secret_live_RrrsLqpzVcoVWf5t4ncQVpzlg2pRpGH9",
        "identity": "steve",
        "amount": "20",
        "bucket": "default"
      }'
      
    • Response

      {
        "id": "423232788708309278",
        "app_id": "423194549918126821",
        "identity_id": 444,
        "type": 4,
        "bucket": "default",
        "amount": -20,
        "date": "2017-08-07T22:26:26.706Z"
      }
      
  • Referral create rule

    • Request

      curl -XPOST https://api.branch.io/v1/eventresponse \
        -d '{
        "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
        "branch_secret": "secret_live_RrrsLqpzVcoVWf5t4ncQVpzlg2pRpGH9",
        "calculation_type": 2,
        "location": 4,
        "type": "credit",
        "event": "signup",
        "metadata": {
          "web_hook_url": "http://www.example.com",
          "amount": "20",
          "bucket": "default"
        },
        "filter": {
        "viewed_tutorial": true,
        "geo": "over_here"
        }
      }
      '
      
    • Response

      {}
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      branch_secret string From your Branch Settings Dashboard
      calculation_type int 0 reward for each use, 1 reward for first use only
      location int 0 all acting users, 1 referring users, 4, referred acting users
      type string credit reward points, web_hook reward webhook callback
      web_hook string The url to call when an event occurs type = web_hook
      amount string Number of credits type = credit
      bucket string The category where the credits are save to type = credit
      filter json This is the set of keys and values that must be contained in the event metadata for this reward to be issued
  • Referral troubleshooting

    • Referral credits cannot go below zero

Webhook

App

  • App create

    • Request

      curl -XPOST https://api.branch.io/v1/app \
        -d '{
        "user_id": "YOUR_USER_ID",
        "app_name": "eneff_test_3",
        "dev_name": "YOUR_NAME",
        "dev_email": "YOUR_EMAIL",
      
        "always_open_app": "1",
      
        "android_app": "2",
        "android_url": "https://www.example.com/ios",
        "android_uri_scheme": "branchtest://",
        "android_package_name": "com.branch.test",
        "android_app_links_enabled": "1",
      
        "ios_app": "2",
        "ios_url": "https://www.example.com/ios",
        "ios_uri_scheme": "branchtest://",
        "ios_store_country": "US",
        "universal_linking_enabled": "1",
        "ios_bundle_id": "com.branch.test",
        "ios_team_id": "PW4Q8885U8",
      
        "fire_url": "https://www.example.com/amazon",
        "windows_phone_url": "https://www.example.com/windows",
        "blackberry_url": "https://www.example.com/blackberry",
        "web_url": "https://www.example.com/web",
        "default_desktop_url": "https://www.example.com/desktop",
      
        "text_message": "click here to download {{ link }}",
      
        "og_app_id": "branch 123",
        "og_title": "branch test",
        "og_description": "branch description",
        "og_image_url": "http://lorempixel.com/400/400/",
      
        "deepview_desktop": "branch_default",
        "deepview_ios": "branch_default",
        "deepview_android": "branch_default"
      }'
      
    • Response

      {
        "alternate_short_url_domain": "a8p0-alternate.app.link",
        "always_open_app": "1",
        "android_app": "2",
        "android_app_links_enabled": "1",
        "android_package_name": "com.branch.test",
        "android_uri_scheme": "branchtest://",
        "android_url": "https://www.example.com/ios",
        "app_key": "423190238827926224",
        "app_name": "eneff_test_3",
        "blackberry_url": "https://www.example.com/blackberry",
        "branch_key": "key_live_hptFZsX5x7Nsvfq4MWdB5ohosCfQ6tjl",
        "branch_secret": "secret_live_sHyeiy240rxQhDF2H2DJYrypRHoq4z1x",
        "creation_date": "2017-08-07T19:37:22.024Z",
        "deepview_android": "branch_default",
        "deepview_desktop": "branch_default",
        "deepview_ios": "branch_default",
        "default_desktop_url": "https://www.example.com/desktop",
        "default_short_url_domain": "a8p0.app.link",
        "dev_email": "YOUR_EMAIL",
        "dev_name": "YOUR_NAME",
        "fire_url": "https://www.example.com/amazon",
        "id": "423190238827926224",
        "ios_app": "2",
        "ios_bundle_id": "com.branch.test",
        "ios_store_country": "US",
        "ios_team_id": "PW4Q8885U8",
        "ios_uri_scheme": "branchtest://",
        "ios_url": "https://www.example.com/ios",
        "og_app_id": "branch 123",
        "og_description": "branch description",
        "og_image_url": "http://lorempixel.com/400/400/",
        "og_title": "branch test",
        "origin": "API: creator id = YOUR_USER_ID, creator email = YOUR_EMAIL",
        "short_url_domain": "",
        "text_message": "click here to download {{ link }}",
        "universal_linking_enabled": "1",
        "web_url": "https://www.example.com/web",
        "windows_phone_url": "https://www.example.com/windows"
      }
      
    • Parameters

      Key Value Usage Required
      user_id string The Dashboard User Id obtained from Branch Account Dashboard
      app_name string The name of the app
      dev_name string The main contact developer name
      dev_email string The main contact developer email. A email is sent on account creation
      android_app string Whether an Android app is enabled. 0 or 1 indicating true
      android_url string The url of the Android store, or package name (e.g. com.android.myapp). android_app must be set to 2
      android_uri_scheme string The Android URI scheme
      android_package_name string The Android package name (e.g. com.android.myapp)
      sha256_cert_fingerprints [string] The SHA256 fingerprints for App Links
      android_app_links_enabled string Whether App Links are enabled. 0 or 1 indicating true
      ios_app string Whether an iOS app is enabled, (0 or 1 indicating true
      ios_url string The url of iOS store, or app id (e.g. id512451233), or a fallback URL for iOS if present. ios_app must be set to 2
      ios_uri_scheme string The iOS URI scheme
      ios_store_country string The country code of the app, defaults to US
      ios_bundle_id string The iOS Bundle Id
      ios_team_id string The iOS Team Id
      universal_linking_enabled string Whether Universal Links should be enabled. 0 or 1 indicating true
      fire_url string The redirect on Fire phone
      windows_phone_url string The redirect on Windows phone
      blackberry_url string The redirect on Blackberry phone
      web_url string Backup website if URLs are null
      default_desktop_url string The default desktop redirect, or null if set to hosted SMS
      text_message string Text message to use for text-me feature, {{ link }} is required and will be replaced with a deep link
      og_app_id string Open Graph app id
      og_title string Open Graph title to be used with link
      og_description string Open Graph description to be used with link
      og_image_url string Open Graph image URL to be used with link
      deepview_desktop string The current deepview selected for the desktop platform
      deepview_ios string The current deepview selected for the iOS platform
      deepview_android string The current deepview selected for the Android platform
  • App read

    • Request

      curl -XGET 'https://api.branch.io/v1/app/key_live_kkDv1y82q6RdiaazE5wAyipkqCnI9i0a?branch_secret=secret_live_igBCicZbq9H3NvYgBishHWuQu4aMbQ0n'
      
    • Response

      {
        "alternate_short_url_domain": "84jv-alternate.app.link",
        "always_open_app": 1,
        "android_app": 2,
        "android_app_links_enabled": true,
        "android_cd_enabled": null,
        "android_cd_hashed": null,
        "android_package_name": "com.branch.test",
        "android_uri_scheme": "branchtest://",
        "android_url": "https://www.example.com/ios",
        "app_key": "423188837653566156",
        "app_name": "eneff_test_3",
        "auto_fetch": null,
        "blackberry_url": "https://www.example.com/blackberry",
        "branch_key": "key_live_kkDv1y82q6RdiaazE5wAyipkqCnI9i0a",
        "branch_secret": "secret_live_igBCicZbq9H3NvYgBishHWuQu4aMbQ0n",
        "creation_date": "2017-08-07T19:31:47.958Z",
        "deepview_android": "branch_default",
        "deepview_desktop": "branch_default",
        "deepview_ios": "branch_default",
        "default_desktop_url": "https://www.example.com/desktop",
        "default_short_url_domain": "84jv.app.link",
        "desktop_uri_scheme": null,
        "dev_email": "YOUR_EMAIL",
        "dev_name": "YOUR_NAME",
        "esp_config": null,
        "fire_url": "https://www.example.com/amazon",
        "id": "423188837653566156",
        "ios_app": 2,
        "ios_bundle_id": "com.branch.test",
        "ios_cd_enabled": null,
        "ios_cd_hashed": null,
        "ios_store_country": "US",
        "ios_team_id": "PW4Q8885U8",
        "ios_uri_scheme": "branchtest://",
        "ios_url": "https://www.example.com/ios",
        "map_utm_params": null,
        "og_app_id": "branch 123",
        "og_description": "branch description",
        "og_image_url": "http://lorempixel.com/400/400/",
        "og_title": "branch test",
        "origin": "API: creator id = YOUR_USER_ID, creator email = YOUR_EMAIL",
        "redirect_domains_whitelist": null,
        "sha256_cert_fingerprints": null,
        "short_url_domain": "",
        "sitemap_enabled": null,
        "text_message": "click here to download {{ link }}",
        "universal_linking_enabled": true,
        "web_url": "https://www.example.com/web",
        "windows_phone_url": "https://www.example.com/windows",
        "zuora_account_id": null
      }
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      branch_secret string From your Branch Settings Dashboard
  • App update

    • Request

      curl -XPUT https://api.branch.io/v1/app/key_live_icCccJIpd7GlYY5oOmoEtpafuDiuyXhT \
        -d '{
        "branch_secret": "secret_live_D3sN7UDL27glpNKZfGPt6BlmKD9txUBp",
        "dev_email": "YOUR_EMAIL",
        "app_name": "eneff_test_3_updated"
      }'
      
    • Response

      {
        "alternate_short_url_domain": "eneff-alternate.app.link",
        "always_open_app": null,
        "android_app": 2,
        "android_app_links_enabled": false,
        "android_cd_enabled": null,
        "android_cd_hashed": null,
        "android_package_name": "com.eneff.branch.example",
        "android_uri_scheme": "enefftest://",
        "android_url": "https://www.example.com",
        "app_key": "299552032371528050",
        "app_name": "eneff_test_3_updated",
        "auto_fetch": null,
        "blackberry_url": null,
        "branch_key": "key_live_icCccJIpd7GlYY5oOmoEtpafuDiuyXhT",
        "branch_secret": "secret_live_D3sN7UDL27glpNKZfGPt6BlmKD9txUBp",
        "creation_date": "2016-08-31T15:23:16.518Z",
        "deepview_android": null,
        "deepview_desktop": null,
        "deepview_ios": "eneff_test_deepview_5blb",
        "default_desktop_url": "https://www.example.com",
        "default_short_url_domain": "eneff.app.link",
        "desktop_uri_scheme": null,
        "dev_email": "YOUR_EMAIL",
        "dev_name": "YOUR_NAME",
        "esp_config": null,
        "fire_url": null,
        "id": "299552032371528050",
        "ios_app": 2,
        "ios_bundle_id": "com.eneff.branch.example",
        "ios_cd_enabled": null,
        "ios_cd_hashed": null,
        "ios_store_country": "US",
        "ios_team_id": "PW4Q8885U8",
        "ios_uri_scheme": "enefftest://",
        "ios_url": "",
        "map_utm_params": null,
        "og_app_id": null,
        "og_description": "branch description updated",
        "og_image_url": "http://lorempixel.com/400/400/",
        "og_title": "hello",
        "origin": null,
        "redirect_domains_whitelist": null,
        "sha256_cert_fingerprints": null,
        "short_url_domain": "",
        "sitemap_enabled": null,
        "text_message": null,
        "universal_linking_enabled": true,
        "web_url": "https://www.cookies.com",
        "windows_phone_url": null,
        "zuora_account_id": null
      }
      
    • Parameters

      Key Value Usage Required
      branch_key string From your Branch Settings Dashboard
      branch_secret string From your Branch Settings Dashboard
      dev_email string The main contact developer email
      ... ... Parameters from App Create

API troubleshooting

Comments