ListExecute

Quick Links

Accounts Accounting Entries Products Customers Sales quotes Sales invoices Suppliers Purchase invoices

Description

The listExecute operation executes a business list strictly based on the definitions returned by listCatalog.

This operation does not require any knowledge of the underlying GraphQL queries or schema.
It relies entirely on the metadata exposed by the catalog.

Most parameters provided to this operation must come from the values returned by listCatalog.

This guarantees:

Sample of result

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

The engine automatically handles:

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

Invoice Number Invoice Date Customer Product Code Quantity Total Net
SI-2026-0145 2026-03-12 Opale PROD-001 2 1,200.00
SI-2026-0138 2026-03-10 Rubis sur ongle PROD-014 1 850.00
SI-2026-0122 2026-03-05 Bague’s en or 13 PROD-007 3 2,100.00
SI-2026-0119 2026-03-04 Carat S.a.r.l PROD-003 5 3,750.00
SI-2026-0115 2026-03-01 Dupond INC PROD-021 1 420.00
Functionality
Important principle

listExecute must always be used after calling listCatalog

  • The catalog defines the exact allowed values for:
    • entityKey
    • filterName
    • orderByName
  • Some filters may require an additional search value.
  • If a value is not present in listCatalog, it is invalid for listExecute.
Key Value
Authorization Bearer Current access Token How to find?
X-TenantId Current tenant id Why deprecated ?
X-OrganizationId Current organization Id How to find?
x-api-key Primary or secondary subscription key of your app How to find?
GraphQL query
query ($input: ListExecuteDtoInput!) {
  listExecute(input: $input) {
    meta {
      entityKey
      context
      filterName
      orderByName
      dateMin
      dateMax
      search
    }
    rows
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
Example Variables (standard filter)
{
  "input": {
    "entityKey": "salesInvoiceLines",
    "filterName": "National invoice lines",
    "orderByName": "Invoice date desc",
    "dateMin": "2026-01-01",
    "dateMax": "2026-03-31",
    "after": null
  }
}
Example Response
{
  "meta": {
    "entityKey": "salesInvoiceLines",
    "context": "Sales Invoice Lines",
    "policy": "salesInvoiceLines",
    "filterName": "National invoice lines",
    "orderByName": "Invoice date desc",
    "dateMin": "2026-01-01",
    "dateMax": "2026-03-31"
    "search": null,
  },
  "edges": [
    {
      "node": {
        "invoiceNumber": "SI-2026-0145",
        "invoiceDate": "2026-03-12",
        "customerName": "Opale",
        "productCode": "PROD-001",
        "quantity": 2,
        "totalNet": 1200.0
      }
    },
    {
      "node": {
        "invoiceNumber": "SI-2026-0132",
        "invoiceDate": "2026-02-27",
        "customerName": "Azur Distribution",
        "productCode": "PROD-014",
        "quantity": 5,
        "totalNet": 3250.0
      }
    }
    // ...  
  ],
  "totalCount": 42,
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "OjE="
  }
}
Example Variables (search-based filter)
{
  "input": {
    "entityKey": "customers",
    "filterName": "Search by company name",
    "search": "Opale",
    "orderByName": "Name asc",
    "after": null
  }
}

{
  "meta": {
    "entityKey": "customers",
    "context": "Customers",
    "policy": "customers",
    "filterName": "Search by company name",
    "orderByName": "Name asc",
    "search": "Opale"
  },
  "edges": [
    {
      "node": {
        "code": "OPALE",
        "socialName": "Opale",
        "customerType": "B2B",
        "countryIsoCodeAlpha2": "FR"
      }
    }
  ],
  "totalCount": 1,
  "pageInfo": {
    "hasNextPage": false,
    "endCursor": null
  }
}

listExecute Input parameters

Fields Type Description
entityKey String List definition identifier
filterName String Business filter applied to the list
search String Search value used by search-based filters
orderByName String Sorting rule applied to the list
dateMin String Start date applied to the list (ISO 8601)
dateMax String End date applied to the list (ISO 8601)
first Int Number of items to retrieve for pagination
after String Cursor for pagination
Info

  • entityKey
    Identifies the exact list definition to execute.
    This value must match an entityKey returned by listCatalog.

  • filterName
    Defines the business filter applied before retrieving the list.
    This value must match exactly one filter name returned by listCatalog.

    Some filters are search-based and contain a %%SEARCH%% placeholder in their definition
    (for example: Search by company name, Search by contact name, Search by city).

  • search
    Defines the search value used by the selected business filter.
    This parameter is required when using a filter that expects a search value
    (for example: Search by company name, Search by contact name, Search by city, Search by zip code).
    It must not be provided when using filters that do not support search.

  • orderByName
    Defines the sorting rule applied to the list.
    This value must match exactly one orderBy name returned by listCatalog.

  • dateMin
    Defines the start date of the business period applied to the list. Date filtering is applied according to the internal business logic of the list. The catalog only indicates whether date range filtering is supported via supportsDateRange returned by listCatalog.
    This parameter is optional. If omitted, no lower bound is applied to the date filter.
    The value must be provided as an ISO 8601 date string (for example 2024-01-01).
    The parameter is represented as a string because listExecute is a generic list engine and accepts dynamic filter values rather than strongly typed date parameters.

  • dateMax
    Defines the end date of the business period applied to the list. Must be greater than or equal to dateMin.
    This parameter is optional. If omitted, no upper bound is applied to the date filter.
    The value must be provided as an ISO 8601 date string (for example 2024-12-31).
    The parameter is represented as a string because listExecute is a generic list engine and accepts dynamic filter values rather than strongly typed date parameters.

  • first
    Defines the maximum number of items to return.
    This parameter is used for pagination and follows the Relay pagination specification.
    Same logic as for standard operations: the default value is 20, and the maximum value is 500.

  • after
    Defines the cursor used for pagination.
    Pagination behavior is consistent across all lists and follows the Relay specification.

listExecute Response

Fields Type Description
meta ListExecuteMeta Echo of the executed list parameters
rows JSON List result
totalCount Int Total number of matching records
pageInfo ListExecutePageInfo Pagination information

meta fields

Fields Type Description
entityKey String Executed list definition identifier
context String Human-readable list context
filterName String Business filter applied
orderByName String Sorting rule applied
dateMin String Effective start date used by the engine
dateMax String Effective end date used by the engine
search String Search value used to restrict results (if any)

pageInfo fields

Fields Type Description
hasNextPage Boolean Indicates whether more results are available
endCursor String Cursor to retrieve the next page
Info

  • meta
    The values returned in this object represent the effective parameters used by the engine to execute the list.
    In some cases, these values may differ from those provided in input if certain parameters were inconsistent or not compatible.
    The meta section always reflects the final parameters actually applied during execution.

  • rows
    Contains the list results following the Relay pagination model.
    The structure of rows depends on the underlying list definition and associated GraphQL query.
    The List API does not alter the shape of the returned business objects.

  • totalCount
    Indicates the total number of records matching the filter, independently of pagination.

  • pageInfo
    Provides pagination metadata (hasNextPage, endCursor) used to retrieve subsequent pages.