Business Central API – leave out CompanyId from the URL

Here’s a nice trick I wanted to share with you simply because I didn’t know this was possible (probably a lot of you already know, but if not – here you go ;-)). It could come in handy in some situations.

You probably are very aware about how we’re supposed to use Business Central API’s in general. Like:

1. Get the CompanyId from a “companies” endpoint
2. Then use that Id to get to the data you’re interested in by including the CompanyId in the URL

For example, to get to the customers of my custom API, it could look something like:

http://bccurrent:7048/BC/waldo/dynex/v1.0/companies(5efbd5e0-0f96-ec11-bb88-000d3a2e8651)/customers

Now – there IS a way to completely disregard that first step, and not include that CompanyId, and STILL be able to get company-specific data.

There are only a few situations of course where this could work, of course, like when you’re only interested in data from some kind of main company, or you only have one company anyway, or you’d have only one company per tenant, or … . But then again – looking at my own experience, these occasions happen more than just once..

The trick is the serversetting “ServicesDefaultCompany“. I must say, there isn’t a lot of details I could find on Microsoft Docs:

• Microsoft Dynamics 365 Business Central Server Configuration – Business Central | Microsoft Docs
• OData Web Services Data Modification – Business Central | Microsoft Docs

And this is the explanation:

Specifies the Dynamics NAV company that the client services, OData web services, and NAS services use as the default company.

What if you don’t use this setting?

Well, like I mentioned above, if you’d call an API, like just for example this URL:

http://bccurrent:7048/BC/waldo/dynex/v1.0/customers

You won’t get anything – you would simply get an error

“Cannot process the request because the default company cannot be found. You can specify a default company in the service configuration file, or specify one for each tenant, or you can add a query string in the form of \”company=[name]\”. You can see the available companies by accessing the default OData web service, Company. For more information, see \”OData Web Services\” in Help. CorrelationId: 9a61a3af-6a87-4b99-879c-33c7ae1cf9e1.”

In all honesty, there is a lot that’s wrong about this message. It seems to be the message that you’d get from its OData counterpart. But it does tell you to add the company in the link, which you can do by adding the CompanyId to the url like this (which you see deviates from what the messages tells us):

http://bccurrent:7048/BC/waldo/dynex/v1.0/companies(5efbd5e0-0f96-ec11-bb88-000d3a2e8651)/customers

BUT .. as the same message also (kind of) explains – when you set the “ServicesDefaultCompany” setting on the server, you can simply perform it without adding the company-id!

Setting up the default company on the NST

You can simply do that with PowerShell by adding the default company in the corresponding setting.

    Set-NAVServerConfiguration `
        -KeyName "ServicesDefaultCompany" `
        -KeyValue "CRONUS BE" `
        -ServerInstance BC

    Set-NAVServerInstance -ServerInstance BC -Restart   

I must say, I did NOT find a way to do this on Business Central SaaS (Online) – if you know, I’d very much appreciate a comment, and I’ll update my post ;-).

Remark

If you only have one company in your system (or tenant), then this setting actually has no use, since it would already provide you the data anyway – it will act the same as if you’d have a default company set up: just take the data from the only company there is.
However: just imagine: in that case, by simply creating a company, the API ecosystem would behave differently: all of a sudden, 3rd parties are not getting data anymore from the main company, because you might have created some kind of copy of a company to test out a posting (admittedly: that’s not a very good reason to create a company anyway ;-)).
Just to say that, IF it makes sense to you to just use one company, or better: IF you have a good reason to dismiss the CompanyId from the API URL, that you should always provide a default company in the “ServicesDefaultCompany” setting to stabilize the behavior. Just be mindful about it :-).

Where we used it

We actually came across a need for this when implementing our mother company: 700 companies, all managed within Business Central OnPrem (sorry.. 🤪 ). The design we chose is: each company is a tenant. So we kind of have 700 tenants, which makes it very scalable.
And .. there is really A LOT of API communication going on between these companies, including from/to 3rd parties. Managing CompanyId is just an extra complexity that was completely unnecessary in this case. It would create confusion and could be time consuming. So this way, we can simply eliminate that extra call, and make the use of APIs much simpler.

Enjoy!