QR Code API
The QR Code API is an HTTP API for creating custom Branch-powered QR codes programmatically. Every QR code embeds a unique Branch Link that supports deep linking and full attribution analytics.
Create QR code
POST/qr-code
Creates a custom Branch-powered QR code. Every QR code embeds a unique Branch Link that supports deep linking and attribution analytics. Returns the rendered QR code as a binary image (PNG or JPEG, configurable via image_format).
Parameters
- branch_keystringRequired
The Branch Key of the originating app, from your Branch Settings, accessible at https://dashboard.branch.io/account-settings/app. Note that the key provided in the example is a dummy.
- qr_code_settingsobjectRequiredExpandable
Predefined set of QR code-related properties that control the overall display of the QR code.
- qr_code_settings.image_formatenum
The output image format that could be either JPEG or PNG.
pngjpegjpg - qr_code_settings.center_logo_urlstring
URL to the image you want as a center logo (for example, “https://cdn.branch.io/branch-assets/00000000-og_image.png”).
- qr_code_settings.widthinteger
Output size of the QR code image. Min 300px. Max 2000px. (Only applicable to JPEG/PNG.)
- qr_code_settings.margininteger
The number of pixels you want for the margin. Min 1px. Max 20px.
- qr_code_settings.code_colorstring
Hex color value of the QR code itself (see https://htmlcolorcodes.com/).
- qr_code_settings.background_colorstring
Hex color value of the background of the QR code itself (see https://htmlcolorcodes.com/).
- qr_code_settings.code_patternenum
Instead of the generic/standard QR code pattern we're used to seeing, you can now use (1) standard, (2) squares, (3) circles, (4) triangles, (5) diamonds, (6) hexagons, and (7) octagons.
1234567 - qr_code_settings.finder_patternenum
The finder pattern refers to the shape seen in the top left, top right, and bottom left of a QR code. You can choose between a square, a rounded square, or a circle. 1 = square, 2 = rounded rectangle, 3 = circle.
123 - qr_code_settings.finder_pattern_colorstring
Hex color value of the finder pattern (see https://htmlcolorcodes.com/).
- qr_code_settings.background_image_urlstring
We can lay the QR code on top of a background image.
- qr_code_settings.code_pattern_urlstring
Direct link to an image to be used as the code pattern itself on the QR code.
- qr_code_settings.finder_eye_colorstring
Hex color value of the finder eye (see https://htmlcolorcodes.com/).
- dataobjectExpandable
The dictionary to embed link data behind the QR code. Accessed as session or install parameters from the SDK. Use the data dictionary for all link control parameters listed in the Deep Link Reference.
- data.$click_install_window_daysstring
Time between a click or a web-to-app auto redirect and an install or reinstall (for example, https://example.app.link/abCdEf123?$click_install_window_days=3).
- data.$click_session_start_window_daysstring
Time between a click or a web-to-app auto redirect and an open or web session start (for example, https://example.app.link/abCdEf123?$click_session_start_window_days=7).
- data.$click_conversion_window_daysstring
Time between a click or a web-to-app auto redirect and a conversion event (for example, https://example.app.link/abCdEf123?$click_session_start_window_days=30). Conversion events include commerce events (for example, purchase, add to cart), all custom events, and all view events like pageviews and content views.
- data.$impression_install_window_daysstring
Time between an ad impression and an install or reinstall (for example, https://example.app.link/abCdEf123?$impression_install_window_days=3).
- data.$impression_conversion_window_daysstring
Time between an ad impression and a conversion event (for example, https://example.app.link/abCdEf123?$impression_session_start_window_days=7). Conversion events include commerce events (for example, purchase, add to cart), all custom events, and all view events like pageviews and content views.
- data.$fallback_urlstring
Change the redirect endpoint for all platforms, so you don't have to enable it by platform. Note that Branch will forward all robots to this URL, which overrides any OG tags entered in the link. System-wide Default URL (set in Link Settings).
- data.$fallback_url_xxstring
Change the redirect endpoint for all platforms based on a lowercase Alpha-2 country code. For example, $fallback_url_de="..." would redirect Germany deep link clicks. You should also set $fallback_url to act as the global redirect in addition to the country-specific ones. Warning: If platform-specific redirects (like $ios_url or $desktop_url) are set, they will override the country-specific redirect. Thus, the recommendation is to only use $fallback_url_xx for the country-specific redirects and $fallback_url to catch all other users.
- data.$desktop_urlstring
Redirect URL for desktop devices. Mobile users will default to the app store.
- data.$ios_urlstring
Change the redirect endpoint for the iOS App Store page for your app (set in Link Settings).
- data.$ios_url_xxstring
Change the redirect endpoint for iOS based on a lowercase Alpha-2 country code (https://www.iso.org/obp/ui/#search). For example, $ios_url_de="..." would redirect Germany deep link clicks. You should also set $ios_url to act as the global redirect in addition to the country-specific ones.
- data.$ipad_urlstring
Change the redirect endpoint for iPads. Falls back to the $ios_url value when unset.
- data.$android_urlstring
Change the redirect endpoint for the Android Play Store page for your app (set in Link Settings).
- data.$android_url_xxstring
Change the redirect endpoint for Android based on a lowercase Alpha-2 country code (https://www.iso.org/obp/ui/#search). For example, $android_url_de="..." would redirect Germany deep link clicks. You should also set $android_url to act as the global redirect in addition to the country-specific ones.
- data.$samsung_urlstring
Redirect to the Samsung Galaxy Store on Samsung devices. Only link-level control. The format should be http://www.samsungapps.com/appquery/appDetail.as?appId={PACKAGE_NAME}
- data.$huawei_urlstring
Redirect to the Huawei App Gallery on Huawei devices. Only link-level control. The format should be https://appgallery.huawei.com/app/{HUAWEI_APP_GALLERY_ID}
- data.$windows_phone_urlstring
Change the redirect endpoint for Windows OS. Windows Phone default URL (set in Link Settings).
- data.$blackberry_urlstring
Change the redirect endpoint for BlackBerry OS. BlackBerry default URL (set in Link Settings).
- data.$fire_urlstring
Change the redirect endpoint for Amazon Fire OS. Fire default URL (set in Link Settings).
- data.$ios_wechat_urlstring
Change the redirect endpoint for WeChat on iOS devices. $ios_url value.
- data.$android_wechat_urlstring
Change the redirect endpoint for WeChat on Android devices. $android_url value.
- data.$web_onlyboolean
Force opening the $fallback_url instead of the app.
- data.$desktop_web_onlyboolean
Force opening the $windows_desktop_url, $mac_desktop_url, $desktop_url, or $fallback_url in this order of precedence instead of the app.
- data.$mobile_web_onlyboolean
Force opening the $ios_url, $android_url, or $fallback_url in this order of precedence instead of the app.
- data.$after_click_urlstring
When a user returns to the browser after going to the app, take them to this URL. iOS only; Android coming soon.
- data.$afterclick_desktop_urlstring
When a user on desktop returns to the desktop browser after going to the desktop app, take them to this URL.
- data.$uri_redirect_modeenum
- 0: This is the default value that yields the standard behavior where we don't try to open the app if the user can see an error.
- 1: Smart redirect mode. Same behavior as 0 until we know the user has the app installed through Branch persona data. In that case, force URI schemes to open the app.
- 2: Forceful redirect mode. Always try to force open the app, even if it risks showing an error message when the app isn't installed.
012 - data.$deeplink_pathstring
Set the deep link path for all platforms, so you don't have to enable it by platform. When the Branch SDK receives a link with this parameter set, it will automatically load the custom URI path contained within.
- data.$android_deeplink_pathstring
Set the deep link path for Android apps. When the Branch SDK receives a link with this parameter set, it will automatically load the custom Android URI path contained within.
- data.$ios_deeplink_pathstring
Set the deep link path for iOS apps. When the Branch SDK receives a link with this parameter set, it will automatically load the custom iOS URI path contained within.
- data.$ios_nativelinkboolean
Set to true to make the link route to a NativeLink™ used for enabling deferred deep linking on iOS 15+ and Private Relay. Can also be set to a deepview/template key to manually trigger the launch of a specific NativeLink™ deepview.
- data.$desktop_deeplink_pathstring
Set the deep link path for desktop apps. You'll have to fetch this parameter and route the user accordingly.
- data.$match_durationinteger
Lets you control the snapshotting match timeout (the time that a click will wait for an app open to match), also known as the attribution window. Specified in seconds.
- data.$always_deeplinkboolean
Set to false to make links always fall back to your mobile site. Doesn't apply to Universal Links or Android App Links.
- data.$ios_redirect_timeoutinteger
Control the timeout that the client-side JS waits after trying to open up the app before redirecting to the App Store. Specified in milliseconds.
- data.$android_redirect_timeoutinteger
Control the timeout that the client-side JS waits after trying to open up the app before redirecting to the Play Store. Specified in milliseconds.
- data.$custom_sms_textstring
Text for SMS link sent for desktop clicks to this link. Must contain {{ link }}. Value of Text me the app page in Settings.
- data.$marketing_titlestring
Set the marketing title for the deep link.
- data.$deeplink_no_attributionboolean
Set to true for the links to only support deep linking without any attribution for that link.
- data.$publicly_indexableinteger
Can't modify here. Needs to be set by the Branch Universal Object.
- data.$canonical_identifierstring
This is the unique identifier for content that will help Branch dedupe across many instances of the same thing. Suitable options: a website with pathing, or a database with identifiers for entities.
- data.$canonical_urlstring
This is the URL set against the identifier.
- data.$content_typestring
This is a label for the type of content present. Apple recommends that you use a uniform type identifier, as described here.
- data.$do_not_processboolean
Lets you control the snapshotting match timeout (the time that a click will wait for an app open to match), also known as the attribution window. Specified in seconds.
- data.$ios_deepviewstring
The name of the deepview template to use for iOS.
- data.$android_deepviewstring
The name of the deepview template to use for Android.
- data.$desktop_deepviewstring
The name of the deepview template to use for desktop.
- data.$ios_passive_deepviewstring
The name of the template to use for iOS.
- data.$android_passive_deepviewstring
The name of the template to use for Android.
- data.$desktop_passive_deepviewstring
The name of the template to use for desktop.
- data.$og_titlestring
Set the title of the deep link as it will be seen in social media displays.
- data.$og_descriptionstring
Set the description of the deep link as it will be seen in social media displays.
- data.$og_image_urlstring
Set the image of the deep link as it will be seen in social media displays.
- data.$og_image_widthinteger
Set the image's width in pixels for social media displays.
- data.$og_image_heightinteger
Set the image's height in pixels for social media displays.
- data.$og_videostring
Set a video as it will be seen in social media displays.
- data.$og_urlstring
Set the base URL of the deep link as it will be seen in social media displays.
- data.$og_typestring
Set the type of custom card format link as it will be seen in social media displays. Don't set this property when sharing deep links on Facebook.
- data.$og_redirectstring
(Advanced, not recommended) Set a custom URL that we redirect the social media robots to in order to retrieve all the appropriate tags.
- data.$og_app_idstring
(Rarely used) Set the app ID tag.
- data.$twitter_cardstring
Set the Twitter card type of the link (for example, player). You must allowlist your deep link with the Twitter Card Validator.
- data.$twitter_titlestring
Set the title of the Twitter card.
- data.$twitter_descriptionstring
Set the description of the Twitter card.
- data.$twitter_image_urlstring
Set the image URL for the Twitter card.
- data.$twitter_sitestring
Set the site for Twitter.
- data.$twitter_app_countrystring
Set the app country for the app card.
- data.$twitter_playerstring
Set the video player's URL. Defaults to the value of $og_video.
- data.$twitter_player_widthinteger
Set the player's width in pixels.
- data.$twitter_player_heightinteger
Set the player's height in pixels.
- data.$custom_meta_tagsstring
Valid stringified JSON dictionary of the tags' keys and values.
Returns
QR code rendered successfully. The response body is the binary image data. Returns 400, 401, 429, and 500 on failure — see the response panel for the error shape.