# 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](/docs/api/business). 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](/docs/getting-started/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

```bash
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"
```

```json
{
  "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=active` returns 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`, `category` or `customer_type` list does not raise an error: the response comes back with an empty `data` and `has_more` set to `false`.
- Some boolean filters do validate their value. On the staff inbox (`GET $BUSINESS_API/inbox`), `unread_only` and `include_archived` accept `true`, `false`, `1`, `0`, `t` and `f`, and return `400` for 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):

```bash
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).

## Next steps

- [Walk through the pages of a list](/docs/getting-started/pagination)
- [Read 400 errors and their codes](/docs/getting-started/errors)
- [Automate queries with the CLI](/docs/guides/automate-cli)

