API Reference

Welcome to the Flowstate API. This page provides a quick start guide and a complete overview of all available endpoints.

Base URL

https://{tenant}.flowstate.inc/api/v1

Replace {tenant} with your tenant subdomain (e.g., acme.flowstate.inc). This is the same domain you use to log in to Flowstate. If your organization has a custom domain configured, use that instead.

All endpoints are prefixed with /org/:orgId where :orgId is your organization identifier. You can find your organization ID in Settings > Organization.

Quick Start

Step 1: Create an API Key

1. Log in to Flowstate
2. Navigate to Settings > API Keys
3. Click Create API Key
4. Give the key a descriptive name (e.g., "HRIS Integration")
5. Select the permissions this key needs (e.g., employees:read, teams:read)
6. Copy the generated key immediately — it will not be shown again

Your key will look like this:

private_k1a2b3c4_xYz987AbCdEfGhIjKlMnOpQrStUv

Step 2: Make Your First Request

Use the API key in the Authorization header as a Bearer token:

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees" \
  -H "Authorization: Bearer private_k1a2b3c4_xYz987AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Step 3: Read the Response

The API responds with a JSON envelope containing data (an array of records) and meta (pagination information):

{
  "data": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "firstName": "Jane",
      "lastName": "Chen",
      "email": "jane.chen@example.com",
      "startDate": "2024-03-15",
      "endDate": null,
      "jobRoleId": "clx9r8q7w6e5",
      "geographyId": "clx3g2h1j0k9",
      "defaultCurrencyCode": "USD",
      "createdAt": "2024-03-15T10:30:00Z",
      "updatedAt": "2024-06-01T14:22:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "hasNextPage": true
  }
}

Step 4: Paginate Through Results

By default, responses return 20 records per page. Use the page and limit query parameters to navigate:

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

See the Pagination & Sorting guide for full details.

Authentication

Every request must include a valid API key in the Authorization header:

Authorization: Bearer private_k1a2b3c4_xYz987AbCdEfGhIjKlMnOpQrStUv

See the Authentication guide for details on creating and managing API keys.

Scenario Support

Add ?scenarioId=cls_abc123 to any endpoint to operate within a scenario. Omit it for live data. See the Scenarios concept guide.

Entities

Entity	Description
Employees	Full-time and part-time employee records
Contractors	External contractors and consulting firms
Vacancies	Open positions and hiring pipeline
Teams	Organizational teams and hierarchy
Projects	Projects with timelines and cost tracking
Assignments	FTE allocations linking people to teams/projects

Configuration Entities

Entity	Description
Cost Centres	Budget tracking and financial allocation centres
Value Streams	Business capability groupings for projects
Work Types	Employment classification categories
Drivers	Project business driver types and measurements
Lifecycle Stages	Project progress stages from planning to completion
Exchange Rates	Currency conversion rates for financial forecasting
Locations	Geographic locations for resource assignments

Common Patterns

List Response Envelope

All list endpoints return data in a consistent envelope:

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

Single Resource Response

Get-by-ID endpoints return the resource directly:

{
  "data": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "firstName": "Jane",
    "lastName": "Chen",
    ...
  }
}

Create / Update Response

Successful create and update operations return the full resource:

{
  "data": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    ...
  }
}

Delete Response

Successful deletions return 204 No Content with an empty body.

Error Response

All errors follow the format described in the Error Handling guide:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Employee not found.",
    "errorId": "err_abc123"
  }
}

Next Steps

• Authentication — API key format, lifecycle, and security best practices
• Pagination & Sorting — Navigate large result sets and sort by any field
• Error Handling — Understand error codes and build resilient integrations
• Getting Started — Learn core Flowstate concepts