Pagination & Sorting

All list endpoints in the Flowstate API return paginated results. This page covers how to navigate pages, control page size, sort results, and search records.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
limit	integer	20	Records per page (min: 1, max: 200)
search	string	—	Full-text search across name/email fields
sortBy	string	varies	Field to sort by (see per-entity tables)
sortDir	string	asc	Sort direction: asc or desc

Response Metadata

Every list response includes a meta object alongside the data array:

{
  "data": [ ... ],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 142,
    "hasNextPage": true
  }
}

Field	Type	Description
page	integer	Current page number
limit	integer	Number of records per page
total	integer	Total number of matching records
hasNextPage	boolean	Whether another page of results exists

Pagination Example

Fetch the second page of employees with 50 records per page:

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees?page=2&limit=50" \
  -H "Authorization: Bearer private_..."

To iterate through all pages programmatically, keep incrementing page until hasNextPage is false:

let page = 1;
let hasNextPage = true;

while (hasNextPage) {
  const response = await fetch(
    `https://{tenant}.flowstate.inc/api/v1/org/${orgId}/employees?page=${page}&limit=100`,
    { headers: { "Authorization": `Bearer ${apiKey}` } }
  );
  const body = await response.json();

  // Process body.data
  processEmployees(body.data);

  hasNextPage = body.meta.hasNextPage;
  page += 1;
}

Sorting

Use sortBy and sortDir to control the order of results:

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees?sortBy=lastName&sortDir=asc" \
  -H "Authorization: Bearer private_..."

Available Sort Fields

Employees

sortBy Value	Description
firstName	First name (A-Z)
lastName	Last name (A-Z)
email	Email address
startDate	Employment start
createdAt	Record creation
updatedAt	Last modification

Contractors

sortBy Value	Description
name	Contractor name
email	Email address
startDate	Contract start
rate	Hourly/daily rate
createdAt	Record creation
updatedAt	Last modification

Vacancies

sortBy Value	Description
role	Role title
status	Vacancy status
targetStartDate	Target start date
targetFillDate	Expected fill date
createdAt	Record creation
updatedAt	Last modification

Teams

sortBy Value	Description
name	Team name
createdAt	Record creation
updatedAt	Last modification

Projects

sortBy Value	Description
name	Project name
startDate	Project start
endDate	Project end
status	Project status
createdAt	Record creation
updatedAt	Last modification

Assignments

sortBy Value	Description
startDate	Assignment start
endDate	Assignment end
fte	FTE allocation
createdAt	Record creation

Cost Centres

sortBy Value	Description
name	Cost centre name
code	Cost centre code
sortOrder	Display order
createdAt	Record creation

Value Streams

sortBy Value	Description
name	Value stream name
sortOrder	Display order
createdAt	Record creation

Work Types

sortBy Value	Description
name	Work type name
sortOrder	Display order
createdAt	Record creation

Drivers

sortBy Value	Description
name	Driver name
category	Driver category
sortOrder	Display order
createdAt	Record creation

Lifecycle Stages

sortBy Value	Description
name	Stage name
category	Stage category
sortOrder	Display order
createdAt	Record creation

Exchange Rates

sortBy Value	Description
fromCurrency	Source currency
toCurrency	Target currency
rate	Conversion rate
effectiveFrom	Effective date
createdAt	Record creation

Locations

sortBy Value	Description
name	Location name
countryCode	Country code
sortOrder	Display order
createdAt	Record creation

Search

Use the search parameter for full-text search across relevant text fields:

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees?search=chen" \
  -H "Authorization: Bearer private_..."

Search queries are case-insensitive and match partial strings. The fields searched depend on the entity:

Entity	Searched Fields
Employees	firstName, lastName, email
Contractors	name, email
Vacancies	role, description
Teams	name, description
Projects	name, description
Cost Centres	name, description
Value Streams	name, description
Work Types	name, description
Drivers	name, description
Lifecycle Stages	name
Exchange Rates	fromCurrency, toCurrency
Locations	name, region

Combining Parameters

All query parameters can be combined:

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees?search=engineering&sortBy=lastName&sortDir=asc&page=1&limit=25&scenarioId=cls_abc123" \
  -H "Authorization: Bearer private_..."