04 November 2018

Getting Started with Dynamics 365 Business Central APIs



API (Application Programming Interface) is an interface which allows applications to talk with each other. Simply put, it is more like a website, where you make a call to the server and you get a response from the server. 

Dynamics 365 Business Central (D365BC) expose many "ready-to-use" APIs which allows seamless integration experience between other service offerings and Dynamics 365 Business Central. Spring 2018 release introduced this new capability to Dynamics 365 Business Central (D365BC) and from every month "ready-to-use" API count is growing. 

Apart from "Ready-to-use" APIs, a user can build their own custom APIs and that will discuss in a separate blog post. 

This blog post will go through basic API requests and will show how to use Postman to test these. 

I have created a collection called "Business Central - API" and in that, I have defined 2 variables so I do not have to type the Base URL over and over and also to store the tenant ID.

Base URL:

 https://api.businesscentral.dynamics.com/v1.0/<your tenant domain>/api/beta  

You need to replace <your tenant domain> with your Business Central ID. 

In the "Authorization" tab set the type to "Basic Auth" and enter Username and Password to login into Dynamics 365 Business Central (D365BC). In here I used Web Service Access Key to login to Dynamics 365 Business Central (D365BC). 

Get Records
Once the Base URL and authentication is set you can create a GET method for {{BaseURL}} which brings all the available APIs as below:

How to retrieve a list of companies available

 {{BaseURL}}/companies  

Return JSON will have all the available companies and their unique IDs

If I want to work with one specific company, then you can store the company ID in an environment variable in Postman. This will make life easy if you going to use this ID in multiple requests. 


I have used a small JavaScript to store the company ID based on the response body. You can achieve this by simply navigating to Test tab and pasting the below script. What this script does it, it cast "responseBody" to a JSON data and then read the company id and the value to "Env_companyID" variable. 

 var JsonData = JSON.parse(responseBody);  
 postman.setEnvironmentVariable("Env_companyID", JsonData.value[0].id);  


Once the script is complete simply execute the {{BaseURL}}/companies. This will return the list of companies and our small JavaScript will store the first company ID in "Env_companyID" variable. 

Now with the stored "Enc_companyID", you can filter the return JSON. 

 {{BaseURL}}/companies/{{Env_companyID}}

From that forward your any request will work on that filtered company. 

Get all the General Ledger Accounts


  {{BaseURL}}/companies/{{Env_companyID}}/accounts


Get all the customers and store first customer ID in Environment Variables


  {{BaseURL}}/companies/{{Env_companyID}}/customers

Set below script it test tab:
 var JsonData = JSON.parse(responseBody);  
 postman.setEnvironmentVariable("Env_customerID",JsonData.value[0].id);  


Filter Records

In this we are filtering customers based on Customer ID we stored in environment variables. 
  {{BaseURL}}/companies/{{Env_companyID}}/customers/{{Env_customerID}}


Update Records

We need "@odata.etag" to update records in Dynamics 365 Business Central (D365BC). Use below JavaScript to store etag in Environment Variables. 

 var JsonData = JSON.parse(responseBody);  
 postman.setEnvironmentVariable("etag", JsonData["@odata.etag"]);  


Once the script is ready to send the request and get the response back. That will set the etag in the Environment Variables. 

After the etag is set we need to change our method to "PATCH" and in the header tab set the "Content-Type" to "application/json" and add another key 'If-Match" and set the value to {{etag}}


In the body of "PATCH" request add below JSON. This means to change the display name to "Tailspin Toys - Update"
 {  
    "displayName": "Tailspin Toys - Update"  
 }  


Execute the command and return JSON will have updated "Display Name"


There are many new possibilities opens up with new APIs and will post more about new APIs and custom APIs. 

Please provide your feedback with a comment. 
Thank you and Regards,
Tharanga Chandrasekara