Lists

Lists in Sage Active allow you to retrieve business-ready datasets such as customers, sales documents, invoice lines, or open items, using predefined and secured business rules.

They are designed to provide consistent, reusable, and controlled access to business data without exposing the underlying GraphQL schema.

There are two approaches to retrieve lists in the API.

Understanding the difference is important.

Approach 1 - Lists on standard queries (historical approach)

This approach consists of calling standard GraphQL business queries directly (customers, salesInvoices, salesInvoiceLines, etc.).

It is flexible but requires:

• knowledge of the underlying GraphQL schema
• knowledge of relations and nested fields
• manual construction of filters and ordering
• strong coupling with the API structure

This approach is still supported for advanced or highly specific use cases.

Approach 2 - List API (catalog-based approach)

The List API already covers the main business domains.

The following business lists are currently available through the catalog:

• Customers
• Suppliers

• Products

• Sales Quotes
• Sales Orders
• Sales Delivery Notes
• Sales Invoices

• Sales Invoice Open Items

• Sales Quote Lines
• Sales Order Lines
• Sales Delivery Note Lines

• Sales Invoice Lines

• Purchase Invoices
• Purchase Invoice Open Items

• Purchase Invoice Lines

• Accounting Entries
• Accounting Entry Lines

This list may evolve over time as new business list definitions are added.

Sample of result

Thanks to the List API, this result is obtained with a single call to listExecute, using only predefined business parameters:

• a list definition (entityKey = salesInvoiceLines)
• a business filter (filter = Unpaid invoice lines)
• a sorting rule (orderBy = Invoice date desc)

The engine automatically handles:

• validation of the list definition
• validation of allowed filters
• validation of allowed sorting rules
• execution of the underlying business query
• pagination and total count

The result returns a business-ready list, without requiring any knowledge of the underlying GraphQL schema.

It provides business-defined lists with predefined filters and sorting rules.

List Catalog

API resources overview / ⚙️List Catalog

This operation exposes a catalog of all available business list definitions across Sage Active.

It allows you to discover:

• which lists exist
• which business filters are available
• which sorting rules are allowed

This is the entry point for lists.

The catalog returns metadata only and does not return business data.

List Execute

API resources overview / ⚙️List Execute

This operation executes a list based on the definitions returned by listCatalog.

You no longer need to:

• know the underlying GraphQL queries
• understand the schema structure
• build custom filters or order clauses

All inputs are validated against the catalog definitions.

Recommendation

For any new development requiring lists, the recommended flow is:

1. Call listCatalog
2. Select the appropriate list definition
3. Choose an available filter and sorting rule
4. Call listExecute

Direct usage of standard GraphQL queries should be reserved for advanced or exceptional cases.

Using listCatalog and listExecute Operations Through an MCP Server

One possible use of the listCatalog and listExecute operations is to expose them as tools through an MCP server.

In this setup, an AI client can dynamically:

• discover available business lists
• understand allowed filters and sorting rules
• execute the appropriate list
• interpret and present the results to the user

This removes the need for hardcoded schema knowledge in the AI layer and ensures that business rules are always respected.

Conversation example