How-To Guides

Querying List Endpoints

Copy page

Querying List Endpoints

Every eTIMS list endpoint (GET collections such as /api/etims/item_classifications/) accepts a common set of query parameters to select only the fields you need, filter, search, and paginate. Use them instead of pulling whole collections and post-processing on the client.

The examples below use the item classifications list, but the same parameters apply to 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).

Field selection (sparse fieldsets)

Pass a comma-separated fields parameter to return only those fields in each result. This shrinks payloads and speeds up responses.

Code
 
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:

Code
 
{
  "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, no spaces required.

• Unknown field names are rejected with 400 Bad Request, and the error lists the allowed fields — so a typo fails fast instead of being silently ignored:

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

• Omit fields to get the full representation.

Filtering

Filter by any model field using ?<field>=<value>. Text fields such as classification_name match case-insensitively on partial values (contains); most other fields match exactly.

Code
 
# 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 that is classification_name and classification_code — a single term matches either:

Code
 
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, not honoured.

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

Why page_size seems "not to work": values above 50 are silently clamped to 50 — you cannot pull more than 50 records in a single page. To find a specific record, filter or search (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

All parameters compose. For example, fetch page 1 of egg-related classifications, returning only code and name, 50 at a time:

Code
 
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) — the classification codes and hierarchy.
• eTIMS API Reference — all endpoints with interactive “Try it”.