Pagination, filtering & sorting

The iBinder APIs are designed to keep network traffic small — list and search endpoints support pagination, filtering, sorting, and free-text search.

How it works

Concern	Mechanism
Pagination	Query string parameters: pageSize, pageNumber
Free-text search	Query string parameter: searchTerm
Filtering	Request body — supports complex multi-key queries
Sorting	Request body — supports multiple sort fields

Because filtering and sorting can get arbitrarily complex, search endpoints use POST rather than GET. Pagination and free-text search live on the query string so URLs are easy to share, log, and bookmark.

Search documents — full example

The Documents API exposes a single search endpoint that combines all of the above. The request below asks for the second page of 250 documents named JohnDoe, filtered to a specific binder and tab, sorted by category:

POST /api/documents?pageSize=250&pageNumber=2&searchTerm=JohnDoe HTTP/1.1
Host: api.ibinder.com
Authorization: Bearer {access_token}
x-ibinder-tenantid: {tenant_id}
Content-Type: application/json

{
  "MetadataFilters": [
    { "metadataElementId": "GLOBAL_BinderId", "valueId": "MNWI5YR89" },
    { "metadataElementId": "GLOBAL_TabId",    "valueId": "SomeTabId" }
  ],
  "SortBy": [
    { "metadataElementId": "GLOBAL_Category", "direction": "asc" }
  ]
}

Filter semantics

• MetadataFilters entries are combined with AND semantics — all conditions must match.
• For enumerated metadata (binder ids, tab ids, status enums) pass the valueId.
• For free-form metadata, the server tolerates both valueId and value keys (the Postman collection uses value).

Sort semantics

• SortBy is an ordered list. The first clause is the primary sort key; ties break to the second clause, and so on.
• direction is "asc" or "desc".

Pagination

• pageNumber is 1-based.
• The response wrapper contains items, totalCount, pageNumber, and pageSize.
• To iterate the full result set, increment pageNumber until pageNumber * pageSize >= totalCount.

Discovering metadata keys

Use GET /binders/{id}/metadataelements at runtime to discover the metadata keys configured on a specific binder. Hardcoding customer-defined keys breaks when the customer reconfigures the binder.

Performance

Very large pages (pageSize > 1000) and very deep pagination can be slow. Prefer filtering to narrow the result set before paginating.