Skip to content
Last updated

💡 Core Concepts

Overview

The Saturation API is designed to feel natural for both production teams and developers. It mirrors how real-world film and commercial productions operate, using human-readable IDs, flexible structures, and a philosophy that keeps things clear and simple.

Design Philosophy:

  • Human-first — Use the same codes and names from your daily workflow.
  • Minimize friction — Fewer calls, richer responses.
  • Stay flexible — Adapt to your production style, not the other way around.

Core Concepts

Workspaces & Projects

  • Workspace — Your company or organization; holds all projects, contacts, and settings.
  • Project — A specific production, campaign, or job. Includes:
    • Multi-phase budget
    • Actual expense tracking
    • Purchase orders
    • Files & Notes

Budgets

Budgets are hierarchical, matching production workflows:

  • Accounts — Major categories (e.g., Above-the-Line)
  • Sub-accounts — Nested for detail
  • Line Items — Specific costs (quantity, rate, calculations)
  • Fringes — Auto payroll taxes/benefits
  • Markups — Percent or flat fees

Phases

Track different versions of a budget:

  • Estimate — Initial proposal
  • Working — In-progress updates
  • Actual — Real costs
  • Committed — Locked POs
  • Rollups — Compare versions (e.g., Variance)

Actuals & Transactions

Actuals — Real expenses:

  • Manual entries (receipts, invoices)
  • Imported transactions via API
  • Converted purchase orders
  • Split across multiple categories

Transactions — Raw bank/credit card data:

  • Import via CSV or API
  • Review and bulk categorize
  • Convert to actuals
  • Maintain audit trail

Contacts

People and companies in your production:

  • Crew — Cast, directors, crew roles
  • Vendors — Rentals, locations, catering
  • Clients — Agencies, brands, studios

Contacts are workspace-level:

  • One record across all projects
  • Consistent IDs for reporting
  • Historical spend analysis

Human-Friendly IDs

Use idMode=user (human-readable) or idMode=system (stable UUIDs).

Key Parameters

  • expands — Pull related data in one call:
GET /projects/film-2025/budget?expands[]=phases&expands[]=lines.contact
  • idMode — ID format:
    • user — Human-friendly ("1100-LABOR")
    • system — UUID/nanoid

Common Workflows

Import a Budget:

POST /projects/my-production/budget
{
  "accountId": "root",
  "lines": [{
    "type": "line",
    "accountId": "1100-LABOR",
    "phaseData": { "estimate": { "quantity": 10, "rate": 25000 } }
  }]
}

Track Actuals:

POST /projects/my-production/actuals
{
  "description": "Camera rental from Panavision",
  "amount": 15000,
  "date": "2024-03-15",
  "lineItemId": "2150",
  "contactId": "vendor-panavision",
  "tags": ["Day-1", "A-Camera"]
}

Import & Convert Transactions:

POST /projects/my-production/transactions/actualize
{
  "transactions": ["txn-001", "txn-002"],
  "lineItemId": "3100",
  "tags": ["Week-1"]
}

Create a Contact:

POST /contacts
{
  "name": "John Smith",
  "company": "Smith Camera Rentals",
  "type": "vendor",
  "email": "john@smithcamera.com",
  "taxId": "12-3456789"
}

Create a Purchase Order:

POST /projects/my-production/purchase-orders
{
  "number": "PO-001",
  "vendor": "contact-123",
  "items": [{
    "description": "Camera Package",
    "amount": 35000,
    "lineItemId": "2150"
  }]
}

Split an Actual:

PUT /projects/my-production/actuals/actual-001
{
  "expanded": true,
  "subActuals": [
    { "lineItemId": "2100", "amount": 10000 },
    { "lineItemId": "2200", "amount": 5000 }
  ]
}

Best Practices

  • Tag data by timeline, location, or department
  • Use fringes for labor accuracy
  • Define global variables for formulas
  • Leverage expands to reduce calls

Next Steps

  1. Create a project
  2. Import a budget
  3. Apply expands and idMode
  4. Integrate with existing tools
Previous page
Next page