Skip to main content
Every collection endpoint in Orgo (GET /api/v1/users, GET /api/v1/events, GET /api/v1/product_payments, …) supports the same pagination, filtering, and ordering query parameters. Once you learn the pattern on one endpoint, the rest follow the same shape. Which filters a given collection accepts is listed under that endpoint’s Parameters in the reference.

Pagination basics

The default page size is set per resource. Most collections use 30, users use 50, and a few reference lists are larger (countries use 1000). The reference shows the default under each endpoint’s itemsPerPage parameter. Whatever the default, a request that asks for more than 100 with itemsPerPage gets at most 100.

page must be a positive whole number

A page of 0, a negative number, or a value that is not a number is a client error. The API answers 400 Bad Request, not 500:
A page beyond the last page is not an error: you get an empty collection. Stop iterating when the collection is empty (or hydra:next is absent), not when you see an error.

pagination=false

Clients cannot switch pagination off in general. The cap exists so one request cannot pull a whole tenant’s data, so ?pagination=false is ignored on almost every collection. The few collections that opt in advertise a pagination parameter in the reference (events and units, for example). On everything else, paginate.

Iterating every page

The reliable way to iterate depends on which response format you accept.

With JSON-LD (the default)

Follow hydra:view.hydra:next until it is absent:

With plain JSON

You get no totals or next-page links. Increment page until the response is shorter than itemsPerPage:
For long-running exports, prefer JSON-LD. hydra:totalItems lets you display progress, and hydra:next is a stable signal that the server still has more rows.

Filtering

Filters are query-string parameters. The available filters differ per resource. Unknown parameters are ignored rather than rejected, so a misspelled filter returns the unfiltered collection. Check that the result shrank.

Exact-value filter

User statuses are uppercase (ACTIVE). Several other statuses, such as event, payment, invoice, contract and vote statuses, are lowercase. Read the enum in the reference rather than guessing.

Filter by relation

For most relations, pass the related resource’s IRI:
Local centers are the exception on the people-related collections (users, contacts, adhesions, fee and product payments, roles). Their localCenter filter takes the numeric id, one value at a time, and answers 400 No Local Center with this id for an id that does not exist or is out of reach:

Multi-value (OR)

Where a filter advertises the name[] form in the reference, repeat the parameter to match any of several values:
User and event-like collections that support it take a keyword parameter. Check the endpoint for it, because the name differs on some resources (contacts use search, events use name):

Date range

Date filters use the [before], [after], [strictly_before], [strictly_after] modifiers on the date properties each resource names:

Presence

exists[property]=true|false tests whether a nullable property is set:

Custom-field filters

User collections accept customFieldValues.field (the custom field) and customFieldValues.value (the stored value), which narrow to members who hold that value for that field:

Ordering

Use order[field]=asc|desc. Order by several fields by repeating the parameter. Only the fields listed under the endpoint’s parameters can be ordered:
The default order varies per resource (usually newest first for “feed” resources like events and newsletters, alphabetic for reference data).

Combining filters, ordering, and pagination

Stack them with &:
URL-encode parameter values that contain spaces or special characters (?name=annual%20meeting). Most HTTP clients do this for you.

Performance notes

  • Collection endpoints fetch and serialize each row’s full read group. For large datasets, apply narrow filters first (?status=ACTIVE shrinks the row count before anything else happens).
  • itemsPerPage=100 is the maximum, so use it for exports to keep the request count low.
  • Sorting by a non-indexed column on a large collection can be slow. Stick to the order[...] fields the reference lists.

  • Content types: the Hydra envelope shape used in JSON-LD pagination
  • Errors: the 400 a bad page produces