# Querying List Endpoints

Every eTIMS list endpoint (`GET` collections such as
`/api/etims/item_classifications/`) takes the same set of query parameters, so
you can pick out the fields you need, filter, search, and paginate. Use them
rather than pulling a whole collection and trimming it on the client.

The examples below use the item classifications list, but the parameters are the
same on every list endpoint.

> **Base URLs.** Development `https://api-dev.slade360edi.com/erp`,
> Production `https://api.erp.slade360.co.ke`. All examples require
> `Authorization: Bearer <access_token>` (see
> [Start Using the eTIMS API](/docs/eTIMS/How-To-Guides/Start-Using-the-eTIMS-API)).

## Field selection (sparse fieldsets)

Pass a comma-separated `fields` parameter and each result comes back with only
those fields. Payloads shrink and responses get faster.

```bash
curl --request GET \
  --url 'https://api-dev.slade360edi.com/erp/api/etims/item_classifications/?fields=classification_code,classification_name' \
  --header 'Authorization: Bearer <access_token>'
```

Each result then contains only the requested fields:

```json
{
  "count": 1240,
  "next": "...?page=2",
  "previous": null,
  "page_size": 15,
  "current_page": 1,
  "total_pages": 83,
  "start_index": 1,
  "end_index": 15,
  "results": [
    { "classification_code": "50131600", "classification_name": "Eggs and egg substitutes" }
  ]
}
```

Notes:

- `fields` is honoured on `GET` requests only. It has no effect on writes.
- List the top-level field names, comma-separated. Spaces are not required.
- An unknown field name is rejected with `400 Bad Request`, and the error lists
  the fields you can use, so a typo shows up straight away instead of being
  quietly dropped:

  ```json
  {
    "fields": "Unknown field(s): ['classificaton_name']. Allowed fields: ['active', 'classification_code', 'classification_name', 'created', 'id', ...]."
  }
  ```

- Omit `fields` to get the full representation.

## Filtering

Filter on any model field with `?<field>=<value>`. Text fields such as
`classification_name` match on partial values and ignore case (`contains`); most
other fields need an exact match.

```bash
# Exact match on the KRA classification code
curl --url '.../api/etims/item_classifications/?classification_code=50131600' ...

# Partial, case-insensitive match on the name
curl --url '.../api/etims/item_classifications/?classification_name=egg' ...
```

## Search

Use `?search=` to match a term across the endpoint's searchable fields. For item
classifications those are `classification_name` and `classification_code`, and a
single term matches either:

```bash
curl --url '.../api/etims/item_classifications/?search=egg' ...
```

## Pagination

List responses are paginated and wrapped in an envelope with `count`, `next`,
`previous`, `page_size`, `current_page`, `total_pages`, `start_index`,
`end_index`, and `results`.

| Parameter | Default | Notes |
|-----------|---------|-------|
| `page` | `1` | Page number to fetch. |
| `page_size` | `15` | Results per page. Capped at 50: larger values are clamped down to 50 rather than honoured. |

```bash
curl --url '.../api/etims/item_classifications/?page=2&page_size=50' ...
```

> **Why `page_size` looks broken.** Values above 50 are clamped to 50 without an
> error, so a single page will never hold more than 50 records. If you are after
> one specific record, filter or search for it (above) rather than paging through
> the whole collection. To pull an entire collection, page through it with
> `?page=N&page_size=50` until `next` is `null`.

## Combining parameters

The parameters compose. This fetches page 1 of the egg-related classifications,
50 at a time, with only the code and name in each result:

```bash
curl --request GET \
  --url 'https://api-dev.slade360edi.com/erp/api/etims/item_classifications/?search=egg&fields=classification_code,classification_name&page=1&page_size=50' \
  --header 'Authorization: Bearer <access_token>'
```

## Related

- [Item Classification (KRA)](/docs/eTIMS/References/Item/Item-Classification) lists the classification codes and the hierarchy.
- [eTIMS API Reference](/etims-api) has all the endpoints, each with an interactive "Try it".