a public API to tie into for fancy integrations. All endpoints are appended to https://api.branch.io
POST /v1/url
Content-Type: application/json
app_id required : The id of the originating app
data optional : The dictionary to embed with the link. Accessed as session or install parameters from the SDK
Note You can customize the Facebook OG tags of each URL if you want to dynamically share content by using the following optional keys in the data dictionary: "$og_app_id" "$og_title" "$og_description" "$og_image_url"
Also, you do custom redirection by inserting the following optional keys in the dictionary: "$desktop_url" "$android_url" "$ios_url" "$ipad_url"
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
identity optional : The identity used to identify the user. If the link is not tied to an identity, there's no need to specify an identity
tags optional : An array of strings, which are custom tags in which to categorize the links by. Recommended syntax: "tags":[t1,t2,t3]
campaign optional : the campaign in which the link will be used. eg: "new_product_launch", etc
feature optional : the feature in which the link will be used. eg: "invite", "referral", "share", "gift", etc
channel optional : the channel in which the link will be shared. eg: "facebook", "text_message"
stage optional : A string value that represents the stage of the user in the app. eg: "level1", "logged_in", etc
{
'url': 'http://bnc.lt/l/deeplink-randomID'
}
This should be used for situations where the longer link is alright and you want to create links on the fly without a POST to the API.
GET https://bnc.lt/a/:app_id?AnyOptionalQueryParamsBelow
Example:
https://bnc.lt/a/:app_id?data=ExampleBase64EncodedString&has_app=no&channel=facebook&stage=level4&feature=affiliate
app_id required : The id of the originating app
data optional : Default is { }. Base 64 Encoded JSON dictionary of parameters to pass into the app. Default redirects can be overridden with $ios_url, $android_url and $desktop_url. The appearance in social media can be customized with the $og_title, $og_description and $og_image_url keys.
has_app optional : Default is 'no'. Possible values are 'yes' or 'no'. If you specify 'yes', we'll try to open up the app immediately instead of sending the clicker to the app store.
type optional : Default is 0. Possible values are 0 or 1. A type of 0 means that the link will pass parameters through install any time that it is clicked and followed by an app session. A type of 0 is a security measure, which prevents the link from passing parameters into the app after the first successful deep link
tags optional : An array of strings, which are custom tags in which to categorize the links by. Recommended syntax: ?tags=a&tags=b&tags=c
campaign optional : the campaign in which the link will be used. eg: "new_product_launch", etc
feature optional : the feature in which the link will be used. eg: "invite", "referral", "share", "gift", etc
channel optional : the channel in which the link will be shared. eg: "facebook", "text_message"
stage optional : A string value that represents the stage of the user in the app. eg: "level1", "logged_in", etc
GET /v1/credits?app_id=[app id]&identity=[identity]
app_id required : The id of the originating app
identity required : The identity used to identify the user.
{
'default': 15,
'other bucket': 4
}
POST /v1/redeem
Content-Type: application/json
app_id required : The id of the originating app
user_id required : The dashboard user id. This will be sent to you by the Branch team to give you access to this API
identity required : The identity used to identify the user.
amount required : The amount of credit to redeem.
bucket optional : 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).
GET /v1/credithistory?app_id=[app id]&identity=[identity]
app_id required : The id of the originating app
identity required : The user ID to retrieve credit history for
bucket optional : 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
},
"referrer": "12345678",
"referree": null
},
{
"transaction": {
"date": "2014-10-14T01:55:09.474Z",
"id": "50388199301710081",
"bucket": "default",
"type": 2,
"amount": -3
},
"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.
POST /v1/event
Content-Type: application/json
app_id required : The id of the originating app
user_id required : The dashboard user id. This will be sent to you by the Branch team to give you access to this API
identity required : The identity used to identify the user.
event required : The event to associate with this identity
metadata optional : any associated parameters to be stored with the event. 1 layer JSON format
nothing
POST /v1/eventresponse
Content-Type: application/json
app_id required : The id of the originating app
user_id required : The dashboard user id. This will be sent to you by the Branch team to give you access to this API
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 - the user completing the action receives credit
- 1 - the user who referred the user completing the action receives 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
- "credit_session" - for referral based rewards, reward the user who referred the a new session
event required : 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 happens
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
GET /v1/app/:app_id?user_id=[user id]
app_id required : The id of the originating app
user_id required : The dashboard user id. This will be sent to you by the Branch team to give you access to this API
{
app_key: "the app key",
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"
}
POST /v1/app
Content-Type: application/json
user_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 : The name of the app
dev_name required : The main contact developer name
dev_email required : The main contact developer email
Note: we'll send an invite message to this email upon account creation.
dev_phone_number optional : The main contact phone number
android_url optional : url of Android store, or namespace (com.android.myapp)
android_uri_scheme optional : the Android URI scheme
ios_url optional : url of iOS store, or app id (id512451233)
ios_uri_scheme optional : the iOS URI scheme
ios_store_country optional : the country code of the app, default to US
web_url optional : backup website if URLs are null
text_message optional : text message to use for text-me feature, {{ link }} will be replaced with short link
og_app_id optional : default Open Graph (OG) app id
og_title optional : default OG title to be used with links
og_description optional : default OG description to be used with links
og_image_url optional : default OG image URL to be used with links
{
app_key: "the app key",
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/:app_id
Content-Type: application/json
app_id required : The id of the originating app
user_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 optional : The name of the app
dev_name optional : The main contact developer name
dev_email optional : The main contact developer email
dev_phone_number optional : The main contact phone number
android_url optional : url of Android store, or namespace (com.android.myapp)
android_uri_scheme optional : the Android URI scheme
ios_url optional : url of iOS store, or app id (id512451233)
ios_uri_scheme optional : the iOS URI scheme
ios_store_country optional : the country code of the app, default to US
web_url optional : backup website if URLs are null
text_message optional : text message to use for text-me feature, {{ link }} will be replaced with short link
og_app_id optional : default Open Graph (OG) app id
og_title optional : default OG title to be used with links
og_description optional : default OG description to be used with links
og_image_url optional : default OG image URL to be used with links
{
app_key: "the app key",
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"
}