Core Concepts

Why This Matters

Operating's data model reflects the complexity of real consulting businesses: projects have multiple people in different roles, work is planned through allocations and tracked through time entries, billing can be time-and-materials or fixed-price, and revenue recognition varies by project type.

Before building integrations, understanding these relationships will help you:

Design efficient data sync strategies (fetch related data in fewer API calls)
Avoid common mistakes (like creating allocations without positions)
Build accurate reports (understand the difference between planned revenue and earned revenue)
Handle edge cases (overlapping allocations, overbooking, tentative vs confirmed work)

Essential Concepts

The Data Model

Operating data model — A comprehensive explanation of how core entities relate:

How projects, clients, and companies organize work
The relationship between persons, positions, allocations, and time entries
Why positions exist as a layer between persons and projects
How rate cards determine billing rates
The difference between planned work (allocations) and actual work (time entries)

Start here if you're building any integration. This guide provides the conceptual foundation for everything else.

Entity Relationships Diagram

API entity relations — A visual overview of the main entities and their connections. Useful as a quick reference while working with the API.

Key Entities Explained

Projects, Clients, and Companies

Projects are the central entity in Operating. Every project belongs to a Company (a legal entity within your organization) and optionally to a Client (the customer purchasing services).

Projects have three types:

Client projects: Billable work for external clients
Internal projects: Non-billable internal work
Time off projects: A special system project for vacation and leave

See: Operating data model for detailed relationships.

Persons, Positions, and Allocations

Persons represent people in your organization (employees and external contractors).

Positions assign a person to a project with a specific role (e.g., "Maria Virtanen as Senior Developer on Stellar Platform project"). A person can have multiple positions on the same project if they play multiple roles.

Allocations represent planned work. Each allocation belongs to a position and defines:

Date range (from/through)
Intensity (percentage of working time)
Status (confirmed or tentative)

Why the position layer exists: It allows different billing rates for the same person on different projects, and enables role-based rate card pricing.

See: Operating data model for the complete picture.

Time Entries and Actuals

Time entries are actual work done. Each time entry records:

Person who did the work
Project the work was for
Date the work happened
Duration in seconds
Optionally: specific task, billing rate, description

Time entries are the "actuals" in planned vs actuals reporting. They drive earned revenue calculations and appear on invoices.

Rate Cards and Billing Rates

Rate cards define hourly billing rates based on:

Competence role (Developer, Designer, Advisor, etc.)
Seniority level (Junior, Mid, Senior, Principal)
Site/location (Helsinki, London, etc.)

Rate cards use a hierarchical fallback logic. If no exact match exists for a role+seniority+site combination, the system falls back to role+seniority, then seniority only, then the base rate.

Positions can have position-specific rates that override the rate card.

External Identifiers

Operating supports external identifiers on most entities, enabling integrations to maintain references between systems without relying on Operating's internal IDs.

For example, when syncing time entries from Harvest:

Store Harvest's time entry ID as externalId in Operating
Use externalId filters to check if an entry already exists
Implement idempotent syncs that create or update based on external ID

See: External Identifiers in Operating API for implementation patterns.