Querying the Dynamics 365 Business Central API using C#

zondag 20 september 2020
Logo of Microsoft Dynamics 365 Business Central Logo of Microsoft Dynamics 365 Business Central
Logo of the C# programming language Logo of the C# programming language

For a new project, I was asked to setup an import/export routine between Microsoft Dynamics 365 Business Central and Exact Online. If you've reached this page, chances are you've noticed that there isn't much practical information to be found about how to query the Dynamics 365 Business Central API. The Microsoft documentation is not very helpful, to say the least, and there aren't many other articles to be found that can help you on your way. I didn't find any.

I wrote this article to share my code for authenticating using basic authentication, and execute a few simple queries. This should get you started using the API.

Further in this article, Microsoft Dynamics 365 Business Central will be abbreviated to DBC.

Authentication

There are 2 ways to authenticate: using basic authentication or using Azure AAD. Refer to this article from Microsoft for more information about both authentication mechanisms. The code below uses basic authentication.

var client = new WebClient();
string credentials = Convert.ToBase64String(Encoding.ASCII.GetBytes(login + ":" + password));
client.Headers[HttpRequestHeader.Authorization] = "Basic " + credentials;
var json = client.DownloadString(url);

To authenticate a request, a login and a password are required. You can't use the password from an existing user of DBC: in the user management, you'll have to generate a Web password. See the screenshot below. The login variable contains "XASP" and the password variable contains the value in the web service password field ("riRJD5NYA...").

User card in Business Central

This code is only part of the request: another part is the URL, which we'll see below.

Fetch companies

This first request is to fetch the companies: to query information (invoices, accounts, ...) from DBC, you'll need a company Id which will be returned as part of the list of companies.

The code below fetches the companies.

string url = string.Format("https://api.businesscentral.dynamics.com/v2.0/{0}/{1}/api/v1.0/companies", tenantId, environment);
var client = new WebClient();
string credentials = Convert.ToBase64String(Encoding.ASCII.GetBytes(login + ":" + password));
client.Headers[HttpRequestHeader.Authorization] = "Basic " + credentials;
var json = client.DownloadString(url);

In this code you can see a tenantId and an environment must be provided. That information can be found in the Help and Support page (use the question mark on the top-right of the screen), on the bottom of the page.

Fetching other data

Now that we have a means to authenticate, and that we have a tenant Id, an environment and a company Id: we can start quering for information.

The example below fetches the sales invoices

string url = string.Format("https://api.businesscentral.dynamics.com/v2.0/{0}/{1}/api/v1.0/companies({2})/salesInvoices", tenantId, environment, companyId);
var client = new WebClient();
string credentials = Convert.ToBase64String(Encoding.ASCII.GetBytes(login + ":" + password));
client.Headers[HttpRequestHeader.Authorization] = "Basic " + credentials;
var json = client.DownloadString(url);