Skip to content
CommissionSight Docs

Workspaces

A workspace partitions a single account’s book of business — for example a parent agency whose child agencies or divisions each manage part of the book. Everything still rolls up to the one account, but each workspace can be uploaded, reported, and priced independently.

Every account always has exactly one default workspace. The multi-workspace feature is an account-level entitlement: until it’s enabled, the account simply operates inside its single default workspace and nothing about uploads or reporting changes. When it’s enabled, the account can have several workspaces and uploads must say which workspace they belong to.

Your account team enables the multi-workspace feature. Once it’s on, your token can list, create, and target workspaces on upload and in reports — all from the API, SDK, or CLI.

Why workspaces (and why it’s not “just the carrier”)

The key property: two workspaces can hold the same carrier for the same period and stay completely separate. A parent agency might have two child agencies that both write Aetna for the same month — each uploads its own Aetna statement, and the two are tracked, scored, and billed independently. Because of this, a workspace is an explicit choice at upload — never inferred from the carrier.

Under the hood each workspace gets its own record identity, so member/policy/period records in one workspace never collide with or overwrite another’s, and month-over-month deltas are computed strictly within a workspace.

Listing your workspaces

Terminal window
curl https://api.commissionsight.com/v1/workspaces -H "Authorization: Bearer $TOKEN"
{
  "enabled": true,
  "workspaces": [
    { "id": "ws_…", "name": "Main book", "isDefault": true },
    { "id": "ws_…", "name": "Medicare", "isDefault": false }
  ]
}
  • enabled: false → the account has a single default workspace; you don’t need to pass a workspaceId anywhere.
  • enabled: true → pass workspaceId on every upload (see below) and optionally on reports.

Creating a workspace

With the multi-workspace feature enabled, create an additional (non-default) workspace by name:

Terminal window
curl -X POST https://api.commissionsight.com/v1/workspaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"Medicare"}'
{ "id": "ws_…", "name": "Medicare", "isDefault": false }

The entitlement is enforced server-side: if the feature isn’t enabled for your account, the request returns 403 feature_not_enabled and nothing is created (a single-workspace account can’t add workspaces via the API). The first/default workspace is created automatically with the account.

Uploading to a workspace

When the feature is enabled, include workspaceId in the upload. Omitting it returns 422 workspace_required.

Terminal window
curl -X POST https://api.commissionsight.com/v1/files \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@march.csv" \
  -F "carrierId=$CARRIER_ID" \
  -F "periodYear=2025" \
  -F "periodMonth=3" \
  -F "workspaceId=$WORKSPACE_ID"

The period-exists / replace gate is scoped to the workspace, so uploading the same carrier+period into a different workspace is accepted (it isn’t treated as a duplicate of another workspace’s file).

Reporting on one workspace vs. the whole book

Every rollup report accepts an optional ?workspaceId. Omit it to roll up the entire account (the parent view); pass it to scope to a single workspace’s slice.

Terminal window
# Whole book (all workspaces)
curl "https://api.commissionsight.com/v1/reports/rollup?period=2025-03" -H "Authorization: Bearer $TOKEN"


# Just one workspace
curl "https://api.commissionsight.com/v1/reports/rollup?period=2025-03&workspaceId=$WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKEN"

This applies to rollup, attrition, attrition-series, and data-quality.

Billing

Billing stays per-member-per-month. Each workspace’s members are billed at that workspace’s negotiated rate (or the account’s rate if it has none), and all workspaces roll up into one invoice with a line item per workspace. A single-workspace account bills exactly as before — one line item.

SDK

import { CommissionSightClient } from '@commissionsight/sdk';
const cs = new CommissionSightClient({ token: process.env.CS_TOKEN });


const { enabled, workspaces } = await cs.listWorkspaces();


// Create one if it doesn't exist yet (requires the multi-workspace feature; 2.3.0+).
let target =
  workspaces.find((w) => w.name === 'Medicare') ??
  (enabled ? await cs.createWorkspace('Medicare') : workspaces[0]);


await cs.uploadFile({
  file,
  carrierId,
  periodYear: 2025,
  periodMonth: 3,
  workspaceId: enabled ? target.id : undefined, // required when enabled
});