Filtering, Search & Sorting

Outcome

Return only the records and relations your workflow needs.

Prerequisites

A list endpoint; supported fields vary by resource.

You'll use

query, search, order_by, include, and cursor pagination.

List endpoints expose a resource-specific combination of filtering, full-text search, sorting, and relation inclusion. Check the endpoint reference for its allowed fields and relations. These parameters work together with pagination.

Filtering with query

The query parameter accepts a JSON object with MongoDB-style operators. Pass it as a URL-encoded JSON string.

Operators

Operator	Description	Example
equals	Exact match (default)	{"status": "sent"} or {"status": {"equals": "sent"}}
not	Not equal	{"status": {"not": "draft"}}
gt	Greater than	{"total": {"gt": 1000}}
gte	Greater than or equal	{"total": {"gte": 1000}}
lt	Less than	{"date": {"lt": "2025-06-01"}}
lte	Less than or equal	{"date": {"lte": "2025-12-31"}}
in	Value in array	{"status": {"in": ["draft", "sent"]}}
notIn	Value not in array	{"status": {"notIn": ["deleted"]}}
contains	Substring match (case-insensitive)	{"name": {"contains": "Acme"}}
startsWith	Starts with	{"name": {"startsWith": "Acme"}}
endsWith	Ends with	{"email": {"endsWith": "@acme.com"}}
between	Range (inclusive)	{"date": {"between": ["2025-01-01", "2025-12-31"]}}

Nested Fields

Some JSON sub-fields can be filtered with dot notation. Only the dotted paths an endpoint lists as allowed fields work, such as customer.name or customer.email on documents. Check the endpoint reference for its list; any other dotted path returns 400 Invalid query field.

?query={"customer.name": {"contains": "Acme"}}

Metadata

metadata keys are not dotted fields: {"metadata.order_id": ...} returns 400 Invalid query field. Pass a nested object under metadata instead, with one entry per key:

?query={"metadata": {"order_id": "ord_123"}}
?query={"metadata": {"order_id": {"equals": "ord_123"}}}
?query={"metadata": {"order_id": {"contains": "ord_12"}}}

A plain value is an exact text match on that key. An operator object such as {"equals": ...} or {"contains": ...} applies that operator to the key’s value. Several keys in the same object must all match.

Related Data

Filter by related records using the relation name:

?query={"payments.type": {"equals": "bank"}}

Examples

Query sdktypescript

Copy

// title: Filtering with SDK
// Filter by total amount
const highValue = await sdk.invoices.list({
  query: JSON.stringify({ total: { gte: 1000 } }),
});

// Filter by customer name
const acme = await sdk.customers.list({
  query: JSON.stringify({ name: { contains: "Acme" } }),
});

// Filter by date range
const thisYear = await sdk.invoices.list({
  query: JSON.stringify({
    date: { between: ["2025-01-01", "2025-12-31"] },
  }),
});

Personalize locallyChecked with SDK v14.27.0

Query curlbash

Copy

# title: Filtering with cURL
# Filter invoices by total amount and date range
curl -G "https://eu.spaceinvoices.com/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Entity-Id: ent_123" \
  --data-urlencode 'query={"total":{"gte":1000},"date":{"gte":"2025-01-01"}}'

Personalize locally

Search

The search parameter performs a full-text search across relevant fields for the resource (e.g., name, email, number). It’s case-insensitive.

?search=Acme

Search fields vary by resource:

• Customers: name, address, city, country, tax number, email
• Invoices: number, customer name, customer email
• Items: name

Sorting with order_by

The order_by parameter controls result ordering. Prefix with - for descending order.

?order_by=name          # A → Z
?order_by=-created_at   # Newest first
?order_by=-date&order_by=number  # By date desc, then number asc

Available sort fields vary by resource. Common fields include id, name, created_at, updated_at, and resource-specific fields like date, total, and number.

Including Relations

The include parameter loads related data in the response. Pass a comma-separated list:

?include=payments

Available relations vary by resource. For example, invoices, credit notes, and advance invoices support including payments.

Combining Parameters

All parameters work together. Here’s a full example:

Combined curlbash

Copy

# title: Combined example
# Filter + search + sort + paginate
curl -G "https://eu.spaceinvoices.com/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Entity-Id: ent_123" \
  --data-urlencode 'query={"total":{"gte":500}}' \
  -d "search=Acme" \
  -d "order_by=-date" \
  -d "limit=10" \
  -d "include=payments"

Personalize locally

This request:

1. Filters invoices with total >= 500
2. Searches for “Acme” across text fields
3. Sorts by date descending (newest first)
4. Limits to 10 results per page
5. Includes payment data in the response