SaaSquatch Help Center

SaaSquatch integrates with Branch Metrics. This technical reference explains the specifics fields, features, API calls and functionality that is used in the integration.

New to Branch? Start Here

This page is a technical reference of the Branch integration. Just getting started for the first time? Check out this article instead:

Branch Metrics Getting Started Guide

🔗 How it Works

The SaaSquatch integration with Branch Metrics works as follows:

  • SaaSquatch referral links (e.g. will start redirecting to Branch links
  • SaaSquatch will create branch links dynamically and set values for data, channel, tags and desktop_url
  • Branch deep link data will include details of the referral code, the Referrer and reward (See field reference below)
  • Analytics Tags will be added to help you track the performance of different platforms.
    • channel: the referral medium. One of FACEBOOK, TWITTER, EMAIL, DIRECT, REMINDER, UNKNOWN
    • tags: the source of the referral. One of STANDARD, MOBILE, UNKNOWN

By default SaaSquatch will send all link clicks through Branch, but will continue to send redirect desktop traffic to your web/desktop site you configured. This is done by setting the Branch value for desktop_url.

  • desktop_url: the landing page you set in our portal when you created your program. If you set a desktop url for your app in Branch, it will be overwritten.

When SaaSquatch creates links dynamically in branch the resulting link, including analytics tags, redirects and custom metadata produce a deep link like the following example:

    "code" : "BRITTANYTEST",
    "$desktop_url" : "http:\/\/\/a\/test_a6whcgrt0vcw3\/widgets\/referral?code=BRITTANYTEST&referralMedium=DIRECT&referralSource=STANDARD",
    "sq_accountId" : "55a43496ebbaff9cf86443d3",
    "sq_amount" : "10",
    "sq_firstName" : "Brittany",
    "sq_id" : "55a43496ebbaf01cebac42cb",
    "sq_imageUrl" : "http:\/\/\/avatar\/77af7eba41d1ccad2bf2c13704637c25?d=mm",
    "sq_lastName" : "Test",
    "sq_referralCode" : "BRITTANYTEST",
    "sq_type" : "PCT_DISCOUNT",
    "sq_unit" : "PERCENT",
    "~channel" : "DIRECT",
    "~tags" : ["STANDARD"],
    "~creation_source" : "API",
    "+is_first_session" : false,
    "+clicked_branch_link" : true

🔗 Data Fields

When SaaSquatch creates links dynamically in branch, it includes a number of metadata fields in the data field. These includes fields from the User, Referral Code and Reward objects.


The Referrer's user ID. This allows you to look up the user in your own system.


The Referrer's account ID. This allows you to look up group or company info. See Shared vs. Solo accounts


The Referrer's first name.


The Referrer's last name.


The Referrer's profile image URL. Note that unlike the user's imageUrl that is used other places in SaaSquatch, like via API, in theme context and in Squatch.js, if this field is set to null it won't actually be null. Instead, when set to null it is instead replaced by a gravatar link that's automatically generated based upon a hash for the Referrer user's email address for when we do not have an image URL for that user. If you want to detect for null images instead you should look for if it's gravatar, or not use this field and look up the value in your user database, or something else.


The Referrer's referral code. This is necessary to attribute the referral.


The amount of the Referred User's reward. This is sort of like the reward fields returned from the lookup referral code API call for explaining a reward but it's different and uses a custom mapping of fields described in the table below to map from this abstract field (that's not available in the API) to other stored or calculated fields for rewards that can be looked up directly via the API, or the fields used in programDetails of theme context or the fields in squatch.js, or other places where rewards are used. Use this convenient mapping table:

  • For rewards of type TIME_CREDIT and CREDIT this field is equal to the reward field called credit
  • For rewards of type PCT_DISCOUNT this field is equal to the reward field called discountPercent
  • For rewards of type FEATURE this field is equal to the reward field called quantity
  • For rewards of type GIFTCODE this field is empty

The unit of the Referred User's reward. For example, in a 10% off referral program this would be PERCENT


The type of the Referred User's reward. One of: PCT_DISCOUNT, TIME_CREDIT, FEATURE, CREDIT, GIFTCODE