Overview of List APIs

Most list endpoints in Invora follow a common HTTP+JSON pattern for pagination, filtering, sorting, and field selection.

Typical endpoint shape: POST /api/{area}/{version}/list

Request body provides filter, sort, pagination, and mask. Response returns items, totalCount, and optional cursor-based pagination fields depending on the area.

Request Structure

• filter: Object defining filtering criteria.
• sort: Object with ordered rules.
• pagination: Object controlling limit and skip.
• mask: Comma-separated field paths to include in the response.

Filtering

Filtering supports composable parts, text search, and time references.

{
  "filter": {
    "part": { /* composable filter parts */ },
    "textSearch": "Acme",
    "timeReference": {
      "referenceDate": "2024-01-01T00:00:00Z",
      "historicalData": false
    },
    "showReplacements": false
  }
}

Example: Composable Filter

Get all non-draft invoices created after 2023-01-01 AND whose buyer has VAT 123456879.

{
  "filter": {
    "part": {
      "and": {
        "operands": [
          { "createdAt": { "fromInclusive": "2023-01-01T00:00:00Z" } },
          { "isDraft": false },
          {
            "details": {
              "accountingCustomerParty": {
                "party": { "partyTaxScheme": { "companyId": "123456879" } }
              }
            }
          }
        ]
      }
    }
  }
}

Sorting

Specify multiple sorting rules in priority order.

{
  "sort": {
    "rules": [
      { "isDeactivated": "SORT_DIRECTION_ASCENDING" },
      { "createdAt": "SORT_DIRECTION_ASCENDING" }
    ]
  }
}

Use SORT_DIRECTION_ASCENDING or SORT_DIRECTION_DESCENDING for each field depending on desired order.

Pagination

Control page size and offset using limit and skip.

{
  "pagination": { "limit": 50, "skip": 10 }
}

To request page n of size x, set limit = x and skip = (n - 1) * x.

Field Selection (mask)

Return only specific fields using mask.

{ "mask": "id,details.legalMonetaryTotal.payableAmount" }

Response Structure

Responses typically include the list of items and counts.

{
  "items": [ /* array of entities */ ],
  "totalCount": 123,
  "nextPageCursor": null
}