Filtering and searching
The query filters each list endpoint accepts, text search with q, what happens to unknown parameters, and why the API has no expand.
Every list endpoint accepts its own set of filters, described on the matching operation in the API Reference. The server applies them before it pages the results, so has_more and next_cursor always describe the filtered set.
How filters combine#
Filters go in the query string and are joined with AND: a record is returned only when it matches every one of them. The paging parameters limit and after work alongside any filter (see Pagination).
The customer list (GET $BUSINESS_API/customers, scope business:customers:read) accepts:
| Parameter | Values | Effect |
|---|---|---|
q |
text | Matches the text anywhere in display_name, ignoring case. |
customer_type |
individual, business |
Only customers of this type. |
category |
residential, commercial, industrial, institutional, government |
Only customers in this tariff category. |
status |
active, suspended, closed |
Only customers in this status. |
Other lists follow the same pattern with their own filters. Invoices (GET $BUSINESS_API/invoices, scope invoices:read) filter by customer_id, account_id, meter_id, reading_id, billing_run_id and status (draft, open, paid, partially_paid, void, uncollectible), and their q searches the invoice number plus the accounts whose holder matches the text.
Example request and response#
curl -sS -G "$BUSINESS_API/customers" \
-H "Authorization: Bearer $API_KEY" \
--data-urlencode "category=institutional" \
--data-urlencode "status=active" \
--data-urlencode "q=escola" \
--data-urlencode "limit=10"
{
"data": [
{
"id": "cus_2kFq9AbN4yPdS8uMqX5iZc0tEfB",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"customer_type": "business",
"category": "institutional",
"display_name": "Escola Primária de Malhangalene",
"status": "active",
"created_at": "2026-11-19T08:20:00.123456789Z",
"updated_at": "2026-11-19T08:20:00.123456789Z"
}
],
"has_more": false
}
Values the server does not recognise#
- A query parameter the endpoint does not read is ignored. A typo such as
stauts=activereturns the list without that filter rather than an error, so check the name against the reference. - On the customer list, a value outside the
status,categoryorcustomer_typelist does not raise an error: the response comes back with an emptydataandhas_moreset tofalse. - Some boolean filters do validate their value. On the staff inbox (
GET $BUSINESS_API/inbox),unread_onlyandinclude_archivedaccepttrue,false,1,0,tandf, and return400for anything else.
No expand#
The API has no expand or include parameter for embedding related objects. Where a related name helps in a list, the resource carries it already: a property includes customer_name, the display name of the customer it belongs to, and leaves it out when that name is unknown. For the full related object, fetch it by ID, for example GET $BUSINESS_API/customers/{id}.
From the CLI#
gotactl api sends any filter as a query parameter with -f (a query parameter on GET, a JSON body field otherwise, written as key=value):
gotactl api GET business:/customers -f category=institutional -f q=escola --json
gotactl customers list has --status (filter by status) and --limit (maximum items to return).