Core concepts

Pagination & filtering

Page through list endpoints and narrow results with common filters.

Every list endpoint accepts the same small set of query parameters for paging, searching, sorting and filtering. Results are returned newest-first by default and always wrapped in the standard response envelope, with paging details under meta.

Pagination parameters

Parameter	Default	Notes
`page`	`1`	1-based page number.
`limit`	`20`	Rows per page. Maximum `1000` — a larger value is clamped.

curl · a page of results

curl "https://gulfpay-production.up.railway.app/api/v1/customers?page=1&limit=20&search=acme&sortDir=desc" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-Company-Id: cmp_123"

The meta block tells you where you are and how much is left, so you never have to guess when to stop:

json · list response

{
  "data": [
    { "id": "cus_1", "name": "Acme Trading LLC" },
    { "id": "cus_2", "name": "Acme Logistics" }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "requestId": "req_...",
    "timestamp": "2026-09-07T09:00:00.000Z"
  }
}

total — total matching rows across all pages.
totalPages — ceil(total / limit); the last page to request.
page / limit — echoed back so you can page relative to them.

Iterating every page

Request pages until page reaches totalPages. Use a larger limitto reduce round-trips, but keep it within the API's maximum and be mindful of rate limits.

shell · walk all pages

# Walk pages until you have them all
page=1
while : ; do
  resp=$(curl -s "https://gulfpay-production.up.railway.app/api/v1/customers?page=$page&limit=100" \
    -H "Authorization: Bearer $TOKEN" -H "X-Company-Id: cmp_123")
  # ...process resp.data...
  total_pages=$(echo "$resp" | sed -n 's/.*"totalPages":\([0-9]*\).*/\1/p')
  [ "$page" -ge "${total_pages:-1}" ] && break
  page=$((page + 1))
done

Searching & sorting

Parameter	Notes
`search`	Free-text match across the resource's searchable fields (name, code, references).
`sortBy`	Column to sort by. Whitelisted per resource — an unknown column falls back to newest-first.
`sortDir`	`asc` or `desc` (default `desc`).

Filtering

Beyond search, list endpoints accept resource-appropriate filters. Combine them freely — they are AND-ed together.

Parameter	Applies to	Example
`status`	Documents	`Draft`, `Posted`, `Cancelled`
`customerId` / `vendorId`	Documents & ledgers	`customerId=cus_123`
`paymentType`	Sales / purchase invoices	`Cash` / `Credit`
`dateFrom` / `dateTo`	Dated documents	`dateFrom=2026-01-01&dateTo=2026-03-31`

Not every filter applies to every resource

Filters are honoured only where they make sense for the resource; an irrelevant filter is simply ignored rather than erroring. The exhaustive, per-resource parameter list is generated in the machine catalogue — see the OpenAPI spec.