Microsoft Business Central API Explained: Environments, Entra Auth, Sandboxes, Queries, and Real-World Integration Pitfalls
- Lennart Svensson
- Nov 3
- 5 min read
If you’re an engineer or solution architect building an integration between your SaaS and Microsoft Dynamics 365 Business Central, this article is for you. Below we’ll share insights from our integration experience, describe how the system behaves, and point out some of the most common pitfalls - so you can save hours of trial and error.
What is Microsoft Dynamics 365 Business Central?
Microsoft Dynamics 365 Business Central is Microsoft’s ERP system for small and medium-sized businesses. Often still called after its predecessor Microsoft Navision. It’s popular across Europe, North America, and other regions with strong localizations, especially in accounting and tax compliance.
Microsoft Business Central exposes a modern REST/OData API and offers standard endpoints for core resources like customers, vendors, invoices, and journals. The API can also be extended with custom entities or published web services — giving you access to almost any data stored in a tenant.
One thing that makes Business Central stand out is its multi-environment model: each tenant can have multiple environments (for example, Production and Sandbox), and within each environment, several companies. This design choice directly affects how you build and authenticate your integrations.
Whats’s the difference between Environments and Companies in Business Central?
Business Central tenants can have multiple environments, while each of them can be Production or Sandbox. Inside each environment, there can be one or several companies – leading to complex structures within bigger organizations.
Both pieces of information are required in every API URL. For example:
If you miss one, you’ll immediately run into “company not found” or 404 errors. To access company data, you must first discover environments using a separate endpoint.
(/environments/v1.1)With Maesn, this is all handled automatically with our Interactive Authentication Feature. Our unified authentication flow discovers the available environments and companies, normalizes them, and connects your application to the right one without any extra setup.
How Microsoft Entra (Azure AD) authentication works in Business Central?
Business Central relies on Microsoft Entra ID (formerly Azure AD) for OAuth authentication, which means that a dedicated Microsoft app must be configured before you can connect. This setup is more complex than a typical “traditional” OAuth app where you simply create the app, define scopes and redirect URLs, and you’re done.
In Business Central, the process involves several consecutive steps:
Create and configure the Microsoft Entra application — this is where you receive several identifiers: Application (client) ID, Object ID, and Directory (tenant) ID. It’s not immediately obvious that the Application IDcorresponds to your client ID.
Add the redirect URL
Add application permissions
Add delegated permissions
Grant admin consent
Generate a client secret
Enter the Application ID inside Business Central
Each of these steps is required — skipping one will cause the authentication to fail.For detailed technical guidance, see the Maesn documentation.
Maesn simplifies this process by guiding partners through the Entra app setup and validating each configuration. During onboarding, we ensure that all necessary permissions are correctly assigned before any API requests are made — eliminating one of the most common blockers when integrating with Business Central.
How to get a Business Central sandbox?
Setting up a sandbox environment for testing is straightforward. With a Microsoft 365 account, you can spin up a free Business Central instance that includes a demo company and full API access.
This environment contains a demo company that behaves as a real production environment with pre-set data and rules. It is perfect for validating authentication, company discovery, and API calls before touching customer data. If you are unable to create a Microsoft 365 account, we can offer a sandbox as well.
Retrieve Related Data (as Line Items in Journal Lines) via Microsoft Business Central API
When working with accounting integrations, developers often face the challenge of retrieving data that includes subordinate records - for example, journal entries that contain sales invoice lines or attachments. At first glance, the Business Central API suggests that two separate requests are required: one for the journal headers and another for the line items.
Fortunately, Business Central provides a more efficient method through Query Objects. By using parameters such as
$expand=journalLines
$expand=salesInvoiceLines and even nested expansions like
$expand=journalLines($expand=attachments)you can define joins between related entities and publish them as a single web service.
This approach significantly reduces the number of API calls and improves synchronization performance.
At Maesn, we apply this technique within our unified API layer to consolidate complex multi-call operations into single, optimized requests to ensure faster and more reliable integrations across systems.
How to set up API Templates in Business Central (and why they matter)
One of the things you have to be aware of in the configuration of the Business Central instance lies in the API Setup page and the templates that live behind it.
When you create entities via the API, like customers, vendors, or sales invoices, Business Central relies on these templates to provide default values for required fields. Fields such as posting groups, tax configurations, or eInvoice routing numbers are pre-filled using these templates.
If they’re missing or misconfigured, API calls can behave inconsistently. You might create customers successfully in your test tenant but fail on a client’s production system — simply because the default template values differ between instances. This happens more often than most developers realize, as Microsoft’s default values are not always identical across localizations.
At Maesn, we support you in preparing the right documentation – including the API templates.
Country-specific differences in Microsoft Business Central
Microsoft provides localized versions of Business Central for many markets. These localizations add specific fields, tax rules, and electronic invoice standards that differ per country. For example, German tenants use different VAT posting groups than French or Dutch ones.
Integrations must be able to handle these differences dynamically. Maesn’s unified API normalizes regional variations and provides a standardized data format across localizations, allowing your product to support multiple markets with one integration.
What Business Central users have to prepare before using an integration
For a successful integration, users have to select which environment and company should be connected - which they do by simply selecting them in the Maesn Interactive auth flow and ensure that API templates are configured. They should also provide an estimate of their data volume to optimize pagination and sync performance.
Maesn supports you with streamlining these checks - validating credentials, testing permissions, and confirming that templates and default values are in place before any live data exchange begins.
Why use Maesn for your Microsoft Business Central API integration
At Maesn, we’ve built a unified API that makes integrating with Business Central as straightforward as connecting to any modern SaaS platform. Our API manages Microsoft Entra authentication, discovers environments and companies automatically, and applies best-practice templates to every new tenant.
We handle pagination, automate retries and country-specific differences behind the scenes. This ensures engineers to focus on building product features instead of debugging integration issues.
In short, we turn weeks of manual setup and testing into a seamless, guided integration process that works reliably across every Business Central instance.
Summary
Microsoft Business Central API is powerful but getting everything set and understanding its architecture - from environments and companies to templates and localizations - is essential for building stable integrations. Many issues arise not from the API itself but from inconsistent configurations across environments.
With Maesn, you can skip those pitfalls entirely. We take care of Entra authentication, environment discovery, support in API template setup, ensuring your Business Central integration works from the very first call.
