Guide

How to read Business Central $metadata and build JSON request bodies

Updated 2 November 2026

Every Business Central API describes itself in a $metadata document: each entity, its fields and their types, and what you can do to it. It's the most reliable reference there is, because it describes your own tenant, including your extensions and custom API pages.

Where to find it

Add /$metadata to the API's root and send a GET with your usual sign-in.

How to read it

It's an XML document, usually a long one. These are the parts that matter:

<EntityType Name="salesOrder">
  <Key><PropertyRef Name="id" /></Key>
  <Property Name="id" Type="Edm.Guid" Nullable="false" />
  <Property Name="customerNumber" Type="Edm.String" MaxLength="20" />
  <Property Name="orderDate" Type="Edm.Date" />
  <NavigationProperty Name="salesOrderLines"
    Type="Collection(Microsoft.NAV.salesOrderLine)" ContainsTarget="true" />
</EntityType>

<EntitySet Name="salesOrders" EntityType="Microsoft.NAV.salesOrder" />

• EntitySet gives the name that goes in the URL: salesOrders.
• Key says what goes in brackets to address one record: salesOrders(<id>).
• Property is a field, with its type and maximum length.
• NavigationProperty leads to related records, such as an order's lines.
• Action and Function are what you can do beyond reading and writing fields, such as posting an invoice.

Turning it into a JSON body

Each field becomes a key, with a value of its type:

Three things to watch for

• Few fields are marked as required. Nullable="false" is often only on the key. So a field can be needed in practice without $metadata saying so. On a sales order, that's the customer.
• Some fields are calculated. Send one and Business Central answers "Control '…' is read-only". Totals and lastModifiedDateTime are typical.
• On an update, a field you send blank is cleared. Include only what you mean to change.

The same thing in Ava

Ava reads $metadata for you. In a request's Body tab, choose From metadata… and it finds the entity from your URL, lets you tick the fields, and writes the JSON with the right types. It leaves out what the server sets and starts an update empty, so you can't blank a record by accident.

In Explore you can tick several entities and add ready-made requests for all of them to a collection. That's especially useful for a custom API page that has no documentation.