A public API to tie into for fancy integrations. All endpoints are appended to https://api.branch.io
For more details on how to create links, see the Branch link creation guide
POST /v1/url
Content-Type: application/json
branch_key required : The Branch key of the originating app.
data optional : The dictionary to embed with the link. Accessed as session or install parameters from the SDK. Use the data dictionary for all link control parameters that you'll find here.
alias optional (max 128 characters) : Instead of our standard encoded short url, you can specify the alias of the link bnc.lt/alexaustin. Aliases are enforced to be unique per domain (bnc.lt, yourapp.com, etc). Be careful, link aliases are unique, immutable objects that cannot be deleted.
NOTE: If you POST to the this endpoint with the same alias, and a matching set of other POST parameters to an existing aliased link, the original will be returned to you. If it clashes and you don't specify a match, will return a HTTP 409 error.
type optional : ADVANCED:
- Set type to 1, to make the URL a one-time use URL. It won't deep link after 1 successful deep link.
- Set type to 2 to make a Marketing URL. These are URLs that are displayed under the Marketing tab on the dashboard (to also set the marketing title of the link, which shows up in the Marketing tab, set the $marketing_title field in the data dictionary to the value that you would like).
- default is set to 0, which is the standard Branch links created via our SDK.git
duration optional : ADVANCED: In seconds. Only set this key if you want to override the match duration for deep link matching. This is the time that Branch allows a click to remain outstanding and be eligible to be matched with a new app session. This is default set to 7200 (2 hours)
Branch analytics parameters optional It's important to tag your links with an organized structure of analytics labels so that the data appears consistent and readable in the dashboard.
identity optional (max 127 characters) : The identity used to identify the user. If the link is not tied to an identity, there's no need to specify an identity.
{
'url': 'http://bnc.lt/l/deeplink-randomID'
}Here's an example cURL that you can paste into the terminal
curl -X POST \
\
-H "Content-Type: application/json" \
\
-d '{"branch_key":"key_live_feebgAAhbH9Tv85H5wLQhpdaefiZv5Dv", "campaign":"new_product_annoucement", "channel":"email", "tags":["monday", "test123"], "data":"{\"name\": \"Alex\", \"email\": \"[email protected]\", \"user_id\": \"12346\", \"$deeplink_path\": \"article/jan/123\", \"$desktop_url\": \"https://branch.io\"}"}' \
\
https://api.branch.io/v1/urlFor more details on how to create links, see the Branch link creation guide
POST /v1/url/bulk/:branch_key
Content-Type: application/jsonA json array of pramameters from Creating a Deep Linking URL. (Note: there is a 100KB limit on the request payload size)
[
{ 'channel': 'branch' },
{ 'channel': "fb", 'data': '{ "$og_title": "deep linking" }' }
]An array of deep linking urls and/or errors in case invalid params.
[
{ 'url': 'http://bnc.lt/l/deeplink-randomID' },
{ 'error': 'error message' } // in case of error
]We've exposed an endpoint to update a certain category of Branch links through our API. Simply issue a PUT to our v1/url endpoint. Certain links may not be updated, which are /c/ and /d/ links.
PUT /v1/url?url=<url>
Content-Type: application/jsonbranch_key required : The Branch key of the originating app. Found in the Branch Dashboard under Settings.
branch_secret required : The paired Branch Secret to the Branch Key making the request. Found in the Branch Dashboard under Settings.
url required : The URL you want to modify, including the host and domain, ex: https://bnc.lt/m/abcd1234, this is included on the URL to request itself:
PUT https://api.branch.io/v1/url?url=https%3A%2F%2Fbnc.lt%2Ftest
analytics/tracking parameters optional
: Branch analytics parameters. Use these keys inside the body of the PUT (NOT inside the 'data' key) to modify data such as channel, campaign, tags, and more.
data optional
: The dictionary to embed with the link. Accessed as session or install parameters from the SDK. Use the data dictionary for all link control parameters that you'll find here.
If you have a link with a URL of https://bnc.lt/test-link, a channel of 'facebook', and data of { "photo_id" : "50", "valid": "true" } and want to update the channel, add an extra value to the dictionary, and add a campaign, here's how that would look:
PUT https://api.branch.io/v1/url?url=https%3A%2F%2Fbnc.lt%2Ftest-link
{
"branch_key" : "key_live_xxxx",
"branch_secret": "secret_live_xxxx",
"channel": "twitter",
"campaign": "twitter-november-campaign",
"data": {
"photo_id": "51",
"photo_name": "John Smith",
"$og_image_url": "https://imgur.com/abcd"
}
}
The new link returns existing data of the link plus the newly added data of the link. Following the example above, this is what would return.
{
"channel": "twitter",
"campaign": "twitter-november-campaign",
"feature": "share-button",
"data": {
"photo_id": "51",
"valid": "true",
"photo_name": "John Smith",
"$og_image_url": "https://imgur.com/abcd",
"~id": "123456789",
"url": "https://bnc.lt/test-link"
},
"alias": "test-link",
"type": 0
}Note, some of this data is existing link data, and some is updated data, but the response will return all data.
There are certain restrictions when attempting to update links.
- Not all links are updateable, namely links with the structure of
bnc.lt/c/orbnc.lt/d/. - You cannot update an alias, e.g. 'https://bnc.lt/test' -> 'https://bnc.lt/test1'.
- You cannot change the identity associated with a Branch link.
- You cannot change the
typeof a link, e.g. a marketing link is type 2, and a standard link generated by our Branch SDK is type 0.
We've exposed an endpoint to view the contents of Branch links through our API. Simply issue a GET to our v1/url endpoint with the URL you'd like to view.
GET /v1/url?url=<url>&branch_key=<branch key>branch_key required : The Branch key of the originating app. Found in the Branch Dashboard under Settings.
url required : The URL you want to modify, including the host and domain, ex: https://bnc.lt/m/abcd1234, this is included on the URL to request itself:
If you have a link with a URL of https://bnc.lt/m/7IhbRIjjmp with Branch key of key_live_lceUuShIL0u4VHJv8BwEQmaitBfAXqCZ:
GET https://api.branch.io/v1/url?url=https%3A%2F%2Fbnc.lt%2Fm%2F7IhbRIjjmp&branch_key=key_live_lceUuShIL0u4VHJv8BwEQmaitBfAXqCZ
The new link returns existing data of the link. Following the example above, this is what would return.
{
"channel": "twitter",
"campaign": "twitter-november-campaign",
"feature": "share-button",
"data": {
"photo_id": "51",
"valid": "true",
"photo_name": "John Smith",
"$og_image_url": "https://imgur.com/abcd",
"~id": "123456789",
"url": "https://bnc.lt/test-link"
},
"alias": "test-link",
"type": 0
}This should be used for situations where the longer link is okay and you want to create links quickly without a POST to the API. Here's a list of instructions on how to build a deep link:
- Start with your Branch domain, http://bnc.lt (or your white labeled one).
- Append /a/your_Branch_key.
- [optional] Append the start of query params '?'
- [optional] Append the Branch analytics tag to keep your data organized in the dashboard. (list here) feature=marketing&channel=email&tags[]=drip1&tags[]=welcome
- [optional] Append any custom deep link parameters &user_id=4562&name=Alex&article_id=456
- [optional] Append your Branch control parameters - see a full list of them here
GET https://bnc.lt/a/<branch_key>?AnyOptionalQueryParamsBelowFor consistency, all parameters are kept in one spot since they are used for everything. Please find them in the Link Configuration guide
GET /v1/app/[branch key]?branch_secret=[branch secret]
branch_key required : The id of the app to retrieve.
branch_secret required : The secret of the app to retrieve.
{
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",
} POST /v1/app
Content-Type: application/jsonuser_id required : The dashboard user id. This will be sent to you by the Branch team to give you access to this API.
app_name required (max 255 characters) : The name of the app.
dev_name required (max 255 characters) : The main contact developer name.
dev_email required (max 255 characters) : The main contact developer email.
Note: we'll send an invite message to this email upon account creation.
android_app optional : Whether an Android app is enabled, (0 or 1 indicating present)
android_url optional : The url of the Android store, or package name (com.android.myapp), or a fallback URL for Android if present.
android_uri_scheme optional : The Android URI scheme.
android_package_name optional : The Android package name (com.android.myapp)
sha256_cert_fingerprints optional : The SHA256 fingerprints for App Links, in array form
android_app_links_enabled optional : Whether App Links are enabled, (0 or 1 indicating true)
ios_app optional : Whether an iOS app is enabled, (0 or 1 indicating present)
ios_url optional : The url of iOS store, or app id (id512451233), or a fallback URL for iOS if present.
ios_uri_scheme optional : The iOS URI scheme.
ios_store_country optional (max 255 characters) : The country code of the app, default to 'US'.
ios_bundle_id optional : The iOS bundle ID
ios_team_id optional : The iOS Team ID
universal_linking_enabled optional : Whether Universal Links should be enabled, (0 or 1 indicating true)
fire_url optional : The redirect on Fire phones
windows_phone_url optional : The redirect on Windows phones
blackberry_url optional : The redirect on Blackberry phones
web_url optional : Backup website if URLs are null.
default_desktop_url optional : The default desktop redirect, or null if set to hosted SMS
text_message optional (max 255 characters) : Text message to use for text-me feature, {{ link }} will be replaced with short link.
og_app_id optional (max 255 characters) : Default Open Graph (OG) app id.
og_title optional (max 255 characters) : Default OG title to be used with links.
og_description optional (max 255 characters) : Default OG description to be used with links.
og_image_url optional (max 255 characters) : Default OG image URL to be used with links.
deepview_desktop optional : The current deepview selected for the desktop platform, (eg "default", "my_template")
deepview_ios optional : The current deepview selected for the iOS platform, (eg "default", "my_template")
deepview_android optional : The current deepview selected for the Android platform, (eg "default", "my_template")
{
branch_key: "the app key of the app created",
branch_secret: "the app secret of the app created",
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"
} PUT /v1/app/:branch_key
Content-Type: application/jsonbranch_key required : The id of the app to modify.
branch_secret required : The branch secret of the app to modify.
app_name optional (max 255 characters) : The name of the app.
dev_name optional (max 255 characters) : The main contact developer name.
dev_email optional (max 255 characters) : The main contact developer email.
android_url optional : The url of the Android store, or namespace (com.android.myapp).
android_uri_scheme optional : The Android URI scheme.
ios_url optional : The url of iOS store, or app id (id512451233)
ios_uri_scheme optional : The iOS URI scheme.
ios_store_country optional (max 255 characters) : The country code of the app, default to US.
web_url optional : Backup website if URLs are null.
text_message optional (max 255 characters) : The text message to use for text-me feature, {{ link }} will be replaced with short link.
og_app_id optional (max 255 characters) : Default Open Graph (OG) app id.
og_title optional (max 255 characters) : Default OG title to be used with links.
og_description optional (max 255 characters) : Default OG description to be used with links.
og_image_url optional (max 255 characters) : Default OG image URL to be used with links.
{
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"
} GET /v1/credits?branch_key=[branch key]&identity=[identity]branch_key required : The Branch key of the originating app.
identity required (max 127 characters) : The identity used to identify the user.
{
'default': 15,
'other bucket': 4
}POST /v1/credits
Content-Type: application/json
branch_key required : The Branch key of the originating app.
branch_secret required : The Branch secret of the originating app.
identity required (max 127 characters) : The identity used to identify the user.
amount required : The amount of credit to award.
bucket optional (max 63 characters) : The name of the bucket to use. If none is specified, defaults to 'default'.
{ success: true }
POST /v1/redeem
Content-Type: application/jsonbranch_key required : The Branch key of the originating app.
branch_secret required : The Branch secret of the originating app.
identity required (max 127 characters) : The identity used to identify the user.
amount required : The amount of credit to redeem. Must be an integer.
bucket optional (max 63 characters) : The name of the bucket to use. If none is specified, defaults to 'default'.
Nothing if successful, or 402 error if not enough credits were available to redeem (this operation is atomic, meaning if two callers try and redeem the same user's credits at the same time, only one will succeed).
If fraud is detected, e.g. users tricking the system to get more credits by referring him/herself, call this API to reconcile the amount from the user's credit balance. If the reconciliation amount is greater than the user's credit balance, the difference amount will be used and the credit balanced will be set to zero.
POST /v1/reconcile
Content-Type: application/jsonbranch_key required : The Branch key of the originating app.
branch_secret required : The Branch secret of the originating app.
identity required (max 127 characters) : The identity used to identify the user.
amount required : The amount of credit to redeem.
bucket optional (max 63 characters) : The name of the bucket to use. If none is specified, defaults to 'default'.
The credit transaction JSON object for the reconciliation
{
"app_id": "55696551485375420",
"identity_id": "55705482546906094",
"date": "2015-02-13T02:27:12.477Z",
"id": "94607584564086264",
"bucket": "default",
"type": 4,
"amount": -5
} GET /v1/credithistory?branch_key=[branch key]&identity=[identity]branch_key required : The Branch key of the originating app.
identity required (max 127 characters) : The user ID to for which to retrieve credit history.
bucket optional (max 63 characters) : The bucket from which to retrieve credit transactions.
begin_after_id optional : The credit transaction id of the last item in the previous retrieval. Retrieval will start from the transaction next to it. If none is specified, retrieval starts from the very beginning in the transaction history, depending on the order.
length optional : The number of credit transactions to retrieve. If none is specified, up to 100 credit transactions will be retrieved.
direction optional : The order of credit transactions to retrieve. If direction is "asc", retrieval is in least recent first order; If direction is "desc", or if none is specified, retrieval is in most recent first order.
[
{
"transaction": {
"date": "2014-10-14T01:54:40.425Z",
"id": "50388077461373184",
"bucket": "default",
"type": 0,
"amount": 5
},
"event" : {
"name": "event name",
"metadata": { your event metadata if present }
},
"referrer": "12345678",
"referree": null
},
{
"transaction": {
"date": "2014-10-14T01:55:09.474Z",
"id": "50388199301710081",
"bucket": "default",
"type": 2,
"amount": -3
},
"event" : {
"name": "event name",
"metadata": { your event metadata if present }
},
"referrer": null,
"referree": "12345678"
}
]referrer : The id of the referring user for this credit transaction. Returns null if no referrer is involved. Note this id is the user id in developer's own system that's previously passed to Branch's identify user API call.
referree : The id of the user who was referred for this credit transaction. Returns null if no referree is involved. Note this id is the user id in developer's own system that's previously passed to Branch's identify user API call.
id : The id can be used and passed as the "begin_after_id" parameter in the subsequent API call to retrieve the next batch of credit transactions.
type : This is the type of credit transaction.
- 0 - A reward that was added automatically by the user completing an action or referral.
- 1 - A reward that was added manually.
- 2 - A redemption of credits that occurred through our API or SDKs.
- 3 or 5 - This is a very unique case where we will subtract credits .automatically when we detect fraud.
- 4 - This is the type when you've called '/v1/reconcile' to reconcile credits manually
POST /v1/event
Content-Type: application/json
branch_key required : The Branch key of the originating app.
branch_secret required : The Branch secret of the originating app.
identity required (max 127 characters) : The identity used to identify the user.
event required (max 63 characters) : The event to associate with this identity.
metadata optional : Any associated parameters to be stored with the event. 1 layer JSON format. (max 255 characters for both keys and values)
nothing
Note: Rules created via the API will not appear on the dashboard. This was done intentionally so as not to overwhelm the dashboard with automatically created rules.
POST /v1/eventresponse
Content-Type: application/jsonbranch_key required : The Branch key of the originating app.
branch_secret required : The Branch secret of the originating app.
calculation_type required : This defines whether the rule can reward a user indefinitely, or a single time.
- 0 - Reward a user continually for the action.
- 1 - User is only eligible for single reward.
location required : The user to reward for the action.
- 0 - Any user completing the action receives credit.
- 1 - The user who referred the user completing the action receives credit.
- 4 - The user completing the action who was referred by another user receives the credit.
type required : The type of event response.
- "web_hook" - Register for a web hook callback when the criteria are met
- "credit" - For referral based rewards, reward the user who caused the referred install.
event required (max 63 characters) : The event string to trigger the reward, eg "completed_purchase".
metadata required : The metadata to define the event response, in JSON format.
For web hooks, use the following keys:
- "web_hook_url" - The url to call when an event occurs.
For credits, use the following keys;
- "amount" - the amount to reward the user
- "bucket" - the bucket to deposit the amount into
filter optional : This is the set of keys and values that must be contained in the event metadata for this reward to be issued, in JSON format.
nothing