Filtering, Search & Sorting

All list endpoints support filtering, full-text search, sorting, and relation inclusion. 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

Filter on JSON fields using dot notation:

?query={"customer.name": {"contains": "Acme"}}
?query={"metadata.order_id": {"equals": "ord_123"}}

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.getInvoices({
  query: JSON.stringify({ total: { gte: 1000 } }),
});

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

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

Query curlbash

Copy

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

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/v1/entities/ent_123/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode 'query={"total":{"gte":500}}' \
  -d "search=Acme" \
  -d "order_by=-date" \
  -d "limit=10" \
  -d "include=payments"

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