Business Central API Filters & OData: Complete Practical Guide

Dynexal • Beginner to Intermediate • 15 min read

When an external application calls Business Central, returning every available record and field is rarely a good integration design. Filters and OData query options let you request only the data you need, reduce unnecessary traffic and make integrations easier to maintain.

What are API filters in Business Central?

Business Central APIs support query parameters that can narrow or shape the response. A common example is $filter, which limits records based on a condition. Microsoft documents filtering for API calls using REST-style filter expressions. For example, an API request can return only open sales invoices above a specified amount.

GET https://api.businesscentral.dynamics.com/v2.0/{environment}/api/v2.0/companies({companyId})/salesInvoices?$filter=status eq 'Open' and totalAmountExcludingTax gt 1000

What is OData?

OData, or Open Data Protocol, is a web protocol for querying and working with tabular data over HTTP. Business Central supports OData web services and OData query options such as filtering, sorting and selecting fields. API endpoints and OData web services are related integration technologies, but their URL structures and capabilities are not identical.

API vs OData: what should you use?

For custom entities, see Business Central Custom API Page. For read-only joined datasets, see Business Central API Query.

1. $filter — return only matching records

$filter is the most important option for integration developers. It limits the records returned by the endpoint.

?$filter=status eq 'Open'

Multiple conditions can be combined with and when the endpoint supports the expression.

?$filter=status eq 'Open' and totalAmountExcludingTax gt 1000

For OData web services, the same concept is expressed through the OData URI:

https://localhost:7048/BC/ODataV4/Company('CRONUS International Ltd.')/Customer?$filter=City eq 'Miami'

Common comparison operators

String values normally use single quotation marks and numeric values do not require quotation marks.

2. and / or

You can combine compatible conditions with logical operators.

?$filter=country eq 'IN' and status eq 'Open'

Be careful with or. Business Central has documented OData limitations; for example, applying OR across two different fields is not supported in some OData scenarios.

?$filter=country eq 'IN' or country eq 'US'

Keep filters simple, test them against your exact endpoint and check the current schema version when using newer filter functionality.

3. String functions

Business Central OData supports several useful string functions, including startswith, endswith and contains in supported scenarios.

?$filter=startswith(Name,'A')

?$filter=contains(Name,'tech')

?$filter=endswith(Code,'01')

Functions such as tolower, toupper and substring are also documented for supported OData filter expressions. Newer schema versions provide more flexible behavior, so test your request against the Business Central version you deploy.

4. $select — return only required fields

$select is useful when the consumer needs only a small subset of an entity.

GET .../customers?$select=id,number,displayName,email

Reducing the response fields can make payloads easier to process and can reduce unnecessary data transfer.

Do not assume that every endpoint supports every query option in exactly the same way. Check the service metadata and test the deployed endpoint.

5. $orderby — sort the response

$orderby requests a particular sort order.

GET .../customers?$orderby=displayName

Descending order can be requested where supported:

GET .../customers?$orderby=displayName desc

Sorting large datasets can have performance implications. Use it intentionally rather than automatically adding complex ordering to every integration request.

6. $top — limit the number of records

$top is useful when an application needs a limited result set, for example during testing or when retrieving a small batch.

GET .../customers?$top=20

For production synchronization of large datasets, do not treat $top as a complete pagination strategy. Use the endpoint's documented paging behavior.

7. $expand — retrieve related data

$expand can request related resources where the endpoint exposes supported navigation properties.

GET .../customers?$select=id,displayName&$expand=contacts

The exact navigation properties available depend on the API metadata. If the property is not exposed by the endpoint, adding $expand will not magically create the relationship.

8. Pagination and large datasets

Large integrations should not assume that one API call returns the complete dataset. Business Central APIs can use server-driven paging, and clients need to follow the paging mechanism returned by the service.

A safe integration pattern is:

1. Request the first page.
2. Read the response and check whether more data is available.
3. Follow the next-page URL or documented continuation mechanism.
4. Process the page.
5. Continue until the service indicates that there are no more records.
6. Store synchronization state when the business process requires incremental processing.

Do not invent a page URL by guessing query parameters. Follow the next link or pagination mechanism returned by the actual API.

Filtering by date

Date and date-time filtering is common in integrations. The exact syntax depends on the API field type and endpoint.

GET .../salesInvoices?$filter=postingDate ge 2026-01-01

When working with date-time fields, pay attention to time zones and the data type exposed in service metadata. Test boundary conditions such as midnight, month-end and daylight-saving transitions where relevant to your integration.

Filtering by multiple values

Some OData schema versions support an in expression for a list of values. Microsoft documents this capability for $schemaversion=2.1.

?$filter=entryNo in (610,612,614)&$schemaversion=2.1

If your target environment does not support the syntax you are using, split the requests or use another supported filtering pattern.

API endpoint structure

For standard Business Central APIs, a typical endpoint starts with the Business Central API base and environment, followed by /api/v2.0.

https://api.businesscentral.dynamics.com/v2.0/{environment}/api/v2.0/{endpoint}

For partner-created APIs, the route includes the publisher, group and version:

https://api.businesscentral.dynamics.com/v2.0/{environment}/api/{publisher}/{group}/{version}/{endpoint}

The company can normally be supplied as part of the URL or as a company query parameter, depending on the API endpoint.

Real Postman example

Suppose you want open sales invoices above 1000 from a standard API. A request can look like this:

GET https://api.businesscentral.dynamics.com/v2.0/{environment}/api/v2.0/companies({companyId})/salesInvoices?$filter=status eq 'Open' and totalAmountExcludingTax gt 1000
Authorization: Bearer {access-token}

For troubleshooting, first remove optional query parameters and confirm that the basic endpoint works. Then add one option at a time.

Combining options

Query options can often be combined when supported by the endpoint.

GET .../customers?$select=id,number,displayName&$filter=blocked eq false&$orderby=displayName&$top=25

A useful development technique is to build requests incrementally:

1. /customers
2. /customers?$filter=blocked eq false
3. /customers?$filter=blocked eq false&$select=id,number,displayName
4. /customers?$filter=blocked eq false&$select=id,number,displayName&$orderby=displayName

API filters vs AL Query filters

These concepts are related but not identical.

• API/OData URI filter: the external client sends a filter expression in the HTTP request.
• DataItemTableFilter: a query object property applies a filter to a query data item.
• ColumnFilter: filters a query column and can be overridden by runtime filtering in relevant scenarios.
• SetFilter / SetRange: AL methods can apply query filters at runtime.

For API Query development, see Business Central API Query.

Common errors

400 Bad Request

Usually check the query syntax, field name, data type, quotation marks and supported operators first.

Field not found

Check the endpoint metadata. The AL table field name is not necessarily the same as the property name exposed by the API.

Filter works in one endpoint but not another

API pages, API queries and OData web services can expose different fields and capabilities. Compare the metadata and use the syntax supported by that specific service.

$expand fails

Verify that the endpoint exposes the requested navigation property and that the relationship is supported.

Too many records

Add a meaningful filter, reduce selected fields and implement correct paging rather than downloading the entire dataset repeatedly.

OR expression fails

Business Central OData has documented limitations around OR expressions across different fields. Simplify the filter or redesign the request when necessary.

Performance best practices

• Filter as early as possible.
• Request only the fields the consumer actually needs.
• Use sensible ordering.
• Process pages incrementally instead of loading everything into memory.
• Avoid repeated full-table synchronization.
• Use webhooks or another change-detection strategy where appropriate.
• Cache stable reference data when the business process allows it.
• Monitor response times, failures and throttling.

Security best practices

• Use Microsoft Entra ID and OAuth-based authentication for Business Central online integrations.
• Never put access tokens or client secrets in browser JavaScript or public repositories.
• Use least-privilege permissions.
• Validate external input before using it in downstream operations.
• Log integration failures without exposing secrets or sensitive tokens.

Recommended integration pattern

External Application
       |
       | OAuth access token
       v
Business Central API
       |
       +---- $filter  -> reduce records
       +---- $select  -> reduce fields
       +---- $orderby -> controlled sorting
       +---- $top     -> small batches/tests
       +---- paging   -> process large datasets
       |
       v
Integration Worker
       |
       +---- Transform
       +---- Validate
       +---- Store / Send

Practical testing checklist

1. Confirm the base endpoint works.
2. Confirm authentication works.
3. Test one simple $filter.
4. Test $select with known properties.
5. Test sorting only after the basic request works.
6. Test paging with more records than one response can return.
7. Test invalid filters and confirm your integration handles 4xx responses.
8. Test empty results.
9. Test large datasets in a sandbox.
10. Review logs and remove secrets before sharing Postman collections or code.

FAQ

Can I use $filter with Business Central APIs?

Yes. Business Central documents filtering for API calls, subject to the capabilities of the endpoint and supported syntax.

Are API filters the same as OData filters?

They use closely related query/filter concepts, but the exact endpoint and supported options depend on whether you are calling a Business Central API or an OData web service.

Does $filter improve performance?

It can reduce the amount of data returned and processed, but actual performance depends on the endpoint, data volume, query design and other factors.

Should I use $top for pagination?

No. Treat $top as a result-size limit where supported. For complete synchronization, follow the endpoint's documented paging mechanism.

Can every OData operator be used in Business Central?

No. Business Central documents supported expressions and known limitations. Always test the expression against the target Business Central version.