Linking to the Dynamics 365 Business Central App

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

The protocol handler for the Business Central Mobile App lets you construct a URL for starting the app on a device, such as a phone or tablet. You can then distribute this URL by e-mail or from a Web page to the users.

The Business Central Mobile App URL is based on the ms-businesscentral URI scheme, which is registered automatically when the app is installed. Invoking a URL based on this scheme will start the app with the provided parameters.

Constructing the URL

To construct a URL, start with ms-businesscentral scheme, and then add additional parameters as needed. Some parameters are required and others are optional.

The structure of a Business Central Mobile App link is very similar to links for the Web client, and has the following syntax:

ms-businesscentral://[<hostname>][/<aadtenantid>][/sandbox]/[?<parameter>=<value>[&<parameter>=<value>]]

[] indicates an optional parameter; all other parameters are required.

<>indicate values that you must supply. Do not include the brackets in the address.

Parameters

The following table describes the parameters for the main part of the URL, which are the parameters up to and including [/sandbox]/.

Parameter	Description	Example
hostname	Domain name for the Dynamics 365 Business Central solution or IP address of the computer/server that hosts it. This is required for an ISV Embed solution. For standard Business Central, you use businesscentral.dynamics.com or you can omit this parameter.	ms-businesscentral://businesscentral.dynamics.com/ ms-businesscentral:/// ms-businesscentral://businesscentral.mysolution.com/
aadtenantid	The unique identifier for a Microsoft Entra tenant. The value can be formatted as a GUID or domain name. This is useful to those who work across multiple Microsoft Entra ID organizations, such as delegated administrators, support personnel or external accountants, because it allows explicitly targeting a Microsoft Entra tenant. If this is omitted, you will be directed to the primary Microsoft Entra tenant or the same Microsoft Entra tenant that you are currently signed in to.	ms-businesscentral://businesscentral.mysolution.com/mysolutionaadtenant.onmicrosoft.com
sandbox	Specifies that the URL should target the Dynamics 365 Business Central sandbox environment instead of a production environment.	ms-businesscentral:/businesscentral.dynamics.com/sandbox/ ms-businesscentral://businesscentral.mysolution.com/sandbox/

The following table describes the optional parameters that are indicated by [?<parameter>=<value>[&<parameter>=<value>]] in the syntax. These parameters are referred to as the query parameters.

Parameter	Description	Example
page	The ID of the page that you want to open directly.	ms-businesscentral:///?page=21 ms-businesscentral://businesscentral.mysolution.com/?page=21
bookmark	The bookmark of the record you want to open. The value of a bookmark is an alphanumeric string of characters, for example, 19%3bGwAAAAJ7BDEAMAAwADA%3d. For the page types Card, CardPart, and Document, the bookmark specifies the record that is shown in the page. For page types List, ListPart, and Worksheet, the bookmark specifies the record that is selected in the list on the page. Important: Bookmarks are generated automatically. You can only determine a value for the bookmark by displaying the page in the client and looking at its address. Therefore, a bookmark is only relevant when the address you are working with has been copied from another instance of the page.	ms-businesscentral:///?bookmark=19%3bGwAAAAJ7BDEAMAAwADA%3d ms-businesscentral://businesscentral.mysolution.com/?bookmark=19%3bGwAAAAJ7BDEAMAAwADA%3d
filter	The filter you want to apply to the page. The filter parameter enables you to display only records from the underlying table of the page that have specific values for one or more fields. For more information about filters, see Filtering Data on the Page.	ms-businesscentral:///?page9305&filter='No.'%20IS%20'1001' ms-businesscentral:///?page9305&filter='Sell-to-Customer-No.'%20IS%20'10000'%20AND%20'Location-Code'%20IS%20'BLUE' ms-businesscentral://businesscentral.mysolution.com/?page9305&filter='No.'%20IS%20'1001' ms-businesscentral://businesscentral.mysolution.com/?page9305&filter='Sell-to-Customer-No.'%20IS%20'10000'%20AND%20'Location-Code'%20IS%20'BLUE'
profile	Specifies the ID of the profile to open, such as accountant or order processor. Be aware that it is possible for two or more profiles have the same ID. Profiles can have a scope of either system or tenant. In addition, tenant profiles can be either user-defined (added by using the Profiles page in the client) or extension-based (added by an extension). Among these different types, the IDs of some profiles might be the same. When there is more than one profile with the same ID as the one you provide, the process for launching the profile is as follows: If there is a matching system profile, it is used. If there is a matching user-defined tenant profile, it is used. If there is only one matching extension-based profile, it is used. If there are two or more extensions-based profiles with the same ID, then the error message More than one profile has the ID '<ID>' within the Tenant scope. appears. In this case, you cannot use the profile parameter for this profile.	ms-businesscentral:///?profile=BUSINESS%20%MANAGER ms-businesscentral://businesscentral.mysolution.com/?profile=BUSINESS%20%MANAGER
customize	Opens the profile for customization, enabling you to change the layout of pages as seen by users of the profile. If you omit the profile, then the default profile opens. For more information, see Customizing the Workspace for Profiles (Roles) in the Business Central Application Help.
company	The company that you want to open in the client. If not provided, the default company is used. CRONUS%20International%20Ltd.	ms-businesscentral:///?'company=CRONUS%20International%20Ltd.' ms-businesscentral://businesscentral.mysolution.com/?'company=CRONUS%20International%20Ltd.'
mode	Whether the page opens in view, edit, or create mode. view only lets you see the data on the page, not modify data. edit lets you to modify data on the page. create lets you to modify data on the page and add new entities.	ms-businesscentral:///?page=21&mode=create ms-businesscentral://businesscentral.mysolution.com/?page=21&mode=create

The query parameters can be in any order. However, the first parameter must be preceded by the ? symbol, and any additional parameters must be preceded by the & symbol.

See Also

Web Client URL
Introducing the Business Central Mobile App