Skip to content

⚒️ API Reference (1.0.0)

The Saturation API lets you work with your workspace data including projects, budgets, actuals, contacts, purchase orders, and attachments.

It is built for real-time collaboration and automation so you can connect it to your internal tools or third-party systems. Any changes you make through the API appear instantly in the web app.

With it, you can:

  • Create, update, and organize projects and phases
  • Build and track multi-phase budgets
  • Sync actuals and purchase orders
  • Manage contacts and crew
  • Upload, retrieve, and organize attachments

🔑 Authentication

GET /api/v1/projects
X-API-Key: YOUR_API_KEY


đź“Š Get everything in one call

GET /projects/my-film/budget?expands[]=phases&expands[]=fringes&expands[]=lines.contact&expands[]=lines.phaseData

Returns the complete budget with all related records, no extra roundtrips.

🏷️ Use your existing codes

GET /projects/my-film/budget/line/1100-LABOR    # Your account code
GET /projects/my-film/budget/phases/estimate    # Your phase name
POST /projects/my-film/actuals                  # Create with your codes
{
  "lineItemId": "2150-CAMERA",
  "amount": 5000
}

The API speaks your language. Use the same codes from your accounting system.

🔄 Common patterns

# Get recent actuals with full details
GET /projects/my-film/actuals?date=2024-03-14&expands[]=contact&expands[]=attachments

# Create a purchase order
POST /projects/my-film/purchase-orders
{
  "number": "PO-001",
  "contactId": "contact-123",
  "items": [{"lineItemId": "2150", "amount": 35000}]
}

# Export complete budget for accounting
GET /projects/my-film/budget?expands[]=phases&expands[]=fringes&expands[]=globals


đź’ˇ Pro tips

  • Create multiple budget lines in one POST to /budget
  • Use tags liberally—they're your flexible second dimension
  • Combine accountId, tags, and date filters for precise queries
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL

https://support.saturation.io

License

Proprietary

Languages
Servers
Production server

https://api.saturation.io/api/v1/

Projects

Create and manage productions, campaigns, or jobs.
Each project has its own budget, actuals, and purchase orders.
Use idMode=user to reference projects by alias (e.g., "nike-spring-2024") instead of system IDs.

Operations

Contacts

Keep crew, contractors, and clients in one workspace-wide directory.
Link contacts to budget lines for automatic contact assignment.
Store tax info and rate cards for quick reuse across projects.

Operations

Rates

Define workspace-wide rate cards for consistent budgeting.
Set crew rates, equipment packages, and standard costs in multiple currencies.
Supports automatic fringe calculations.

Operations

Transactions

Import raw bank and card data, match to contacts, and convert to actuals.
Maintains a full audit trail from bank statement to budget line.

Operations

Budget

Build hierarchical budgets with accounts, line items, subtotals, and markups.
Use expands[]=phases&expands[]=fringes&expands[]=globals&expands[]=lines.contact&expands[]=lines.phaseData
to fetch complete budget data in one call.
Reference budget lines by account code (e.g., "1100-LABOR") with idMode=user.

Operations

Get budget

Request

Retrieve budget information for a project

Security
ApiKeyAuth
Path
projectIdstringrequired

Project identifier (alias or ID)

Example: nike-spring-2024
Query
accountIdstring

Filter by account ID or code (defaults to root account)

Example: accountId=2150
phaseIdstring or Array of strings

Filter by phase ID(s)

Example: phaseId=estimate&phaseId=actual
One of:
string
includeHiddenPhasesboolean

Include hidden phases in the response

tagsstring or Array of strings

Filter budget by tag names (can be single tag or array of tags)

Example: tags=Marketing&tags=Engineering
One of:
string
tagFilterModestring

How to apply the tag filter

Default "contains"
Enum"contains""excludes"
Example: tagFilterMode=contains
expandsArray of strings

Include related data in the response

Items Enum"fringes""phases""globals""lines.contact""lines.phaseData"
Example: expands=phases&expands=lines.contact
idModestring

ID interpretation mode. Controls how path and query parameter IDs (like lineId, accountId, phaseId) are interpreted - 'user' for human-readable IDs (account codes, phase names), 'system' for database IDs (UUIDs/nanoids). Also affects the format of IDs in responses.

Default "user"
Enum"user""system"
Example: idMode=user
curl -i -X GET \
  'https://api.saturation.io/api/v1/projects/nike-spring-2024/budget?accountId=2150&phaseId=estimate%2Cactual&includeHiddenPhases=true&tags=Marketing%2CEngineering&tagFilterMode=contains&expands=phases%2Clines.contact&idMode=user' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Budget information

Bodyapplication/json
accountobject(Account)required
account.​idstringrequired

Account system identifier

Example: "acc-xyz-789"
account.​accountIdstring or null

User-friendly account code/number

Example: "2150"
account.​descriptionstring or null

Account description

Example: "Camera Equipment"
account.​pathstringrequired

Hierarchical path in budget tree

Example: "/production/equipment"
account.​linesArray of objects(BudgetLine)required

Budget lines within this account

account.​lines[].​typestringrequired

Type of budget line

Enum"line""account""subtotal""markup""fringes"
Example: "line"
Discriminator
account.​lines[].​idstringrequired

Budget line identifier (system ID)

Example: "line-001"
account.​lines[].​accountIdstring or null

Account identifier (user-friendly ID like account code)

Example: "2150"
account.​lines[].​descriptionstring or null

Budget line description

Example: "RED Camera Package Rental"
account.​lines[].​pathstringrequired

Hierarchical path in budget tree (e.g., /2000/2150)

Example: "/production/equipment/cameras"
account.​lines[].​totalsobjectrequired

Calculated totals for each phase

Example: {"estimate":25000,"actual":22500,"variance":2500}
account.​lines[].​totals.​property name*numberadditional property
account.​lines[].​tagsArray of strings

Tags for categorization and filtering

Example: ["Day-1","A-Camera","Equipment"]
account.​lines[].​contactobject(Contact)
account.​lines[].​phaseDataobject

Detailed phase-specific data (expandable)

account.​totalsobjectrequired

Calculated totals for each phase

Example: {"estimate":150000,"actual":125000,"variance":25000}
account.​totals.​property name*numberadditional property
account.​contactobject(Contact)
subAccountsobject

Sub-account hierarchy

phasesArray of objects(Phase)

Budget phases

fringesArray of objects(Fringe)

Fringe benefits

globalsArray of objects(Global)

Global variables

Response
application/json
{
  "account": {
    "id": "acc-xyz-789",
    "accountId": "2150",
    "description": "Camera Equipment",
    "path": "/production/equipment",
    "lines": [ … ],
    "totals": { … },
    "contact": { … }
  },
  "subAccounts": {
    "property1": { … },
    "property2": { … }
  },
  "phases": [
    { … }
  ],
  "fringes": [
    { … }
  ],
  "globals": [
    { … }
  ]
}

Create budget lines

Request

Add new budget lines to an existing account within the budget hierarchy.

This endpoint creates line items, sub-accounts, subtotals, or markups at the specified location in your budget structure. The target account must already exist in the budget hierarchy.

Use accountId: "root" to add lines at the top level of your budget.

Security
ApiKeyAuth
Path
projectIdstringrequired

Project identifier (alias or ID)

Example: nike-spring-2024
Bodyapplication/jsonrequired
accountIdstring

Target account ID or account code where lines will be added. Use "root" for top-level budget. The account must already exist in the budget hierarchy.

Example: "root"
linesArray of objects

Array of budget lines to create (line items, accounts, subtotals, or markups)

insertobject

Where to insert the new lines

idModestring

ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs

Default "user"
Enum"user""system"
Example: "user"
curl -i -X POST \
  https://api.saturation.io/api/v1/projects/nike-spring-2024/budget \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "accountId": "root",
    "lines": [
      {
        "type": "account",
        "accountId": "1000",
        "description": "Above-the-Line"
      },
      {
        "type": "account",
        "accountId": "2000",
        "description": "Below-the-Line"
      }
    ]
  }'

Responses

Budget lines created successfully

Bodyapplication/json
accountobject(Account)required
account.​idstringrequired

Account system identifier

Example: "acc-xyz-789"
account.​accountIdstring or null

User-friendly account code/number

Example: "2150"
account.​descriptionstring or null

Account description

Example: "Camera Equipment"
account.​pathstringrequired

Hierarchical path in budget tree

Example: "/production/equipment"
account.​linesArray of objects(BudgetLine)required

Budget lines within this account

account.​lines[].​typestringrequired

Type of budget line

Enum"line""account""subtotal""markup""fringes"
Example: "line"
Discriminator
account.​lines[].​idstringrequired

Budget line identifier (system ID)

Example: "line-001"
account.​lines[].​accountIdstring or null

Account identifier (user-friendly ID like account code)

Example: "2150"
account.​lines[].​descriptionstring or null

Budget line description

Example: "RED Camera Package Rental"
account.​lines[].​pathstringrequired

Hierarchical path in budget tree (e.g., /2000/2150)

Example: "/production/equipment/cameras"
account.​lines[].​totalsobjectrequired

Calculated totals for each phase

Example: {"estimate":25000,"actual":22500,"variance":2500}
account.​lines[].​totals.​property name*numberadditional property
account.​lines[].​tagsArray of strings

Tags for categorization and filtering

Example: ["Day-1","A-Camera","Equipment"]
account.​lines[].​contactobject(Contact)
account.​lines[].​phaseDataobject

Detailed phase-specific data (expandable)

account.​totalsobjectrequired

Calculated totals for each phase

Example: {"estimate":150000,"actual":125000,"variance":25000}
account.​totals.​property name*numberadditional property
account.​contactobject(Contact)
subAccountsobject

Sub-account hierarchy

phasesArray of objects(Phase)

Budget phases

fringesArray of objects(Fringe)

Fringe benefits

globalsArray of objects(Global)

Global variables

Response
application/json
{
  "account": {
    "id": "acc-xyz-789",
    "accountId": "2150",
    "description": "Camera Equipment",
    "path": "/production/equipment",
    "lines": [ … ],
    "totals": { … },
    "contact": { … }
  },
  "subAccounts": {
    "property1": { … },
    "property2": { … }
  },
  "phases": [
    { … }
  ],
  "fringes": [
    { … }
  ],
  "globals": [
    { … }
  ]
}

Get budget line

Request

Retrieve a specific budget line by its identifier.

The lineId parameter accepts both user-friendly IDs and system IDs:

  • With idMode=user (default): Use account codes like "1100" or "camera-dept"
  • With idMode=system: Use UUIDs/nanoids like "abc123xyz" or "550e8400-e29b-41d4-a716"
Security
ApiKeyAuth
Path
projectIdstringrequired

Project identifier (alias or ID)

Example: nike-spring-2024
lineIdstringrequired

Budget line identifier. Can be either a user-friendly ID (e.g., account code) or a system ID (UUID/nanoid), depending on the idMode parameter

Query
tagsstring or Array of strings

Filter budget line by tag names (can be single tag or array of tags)

Example: tags=Marketing&tags=Engineering
One of:
string
tagFilterModestring

How to apply the tag filter

Default "contains"
Enum"contains""excludes"
Example: tagFilterMode=contains
expandsArray of strings

Include related data in the response

Items Enum"contact""phaseData"
Example: expands=contact&expands=phaseData
idModestring

ID interpretation mode. Controls how path and query parameter IDs (like lineId, accountId, phaseId) are interpreted - 'user' for human-readable IDs (account codes, phase names), 'system' for database IDs (UUIDs/nanoids). Also affects the format of IDs in responses.

Default "user"
Enum"user""system"
Example: idMode=user
curl -i -X GET \
  'https://api.saturation.io/api/v1/projects/nike-spring-2024/budget/line/{lineId}?tags=Marketing%2CEngineering&tagFilterMode=contains&expands=contact%2CphaseData&idMode=user' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Budget line details

Bodyapplication/json
typestringrequired

Type of budget line

Enum"line""account""subtotal""markup""fringes"
Example: "line"
Discriminator
idstringrequired

Budget line identifier (system ID)

Example: "line-001"
accountIdstring or null

Account identifier (user-friendly ID like account code)

Example: "2150"
descriptionstring or null

Budget line description

Example: "RED Camera Package Rental"
pathstringrequired

Hierarchical path in budget tree (e.g., /2000/2150)

Example: "/production/equipment/cameras"
totalsobjectrequired

Calculated totals for each phase

Example: {"estimate":25000,"actual":22500,"variance":2500}
totals.​property name*numberadditional property
tagsArray of strings

Tags for categorization and filtering

Example: ["Day-1","A-Camera","Equipment"]
contactobject(Contact)
phaseDataobject

Detailed phase-specific data (expandable)

Response
application/json
{
  "type": "line",
  "id": "line-001",
  "accountId": "2150",
  "description": "RED Camera Package Rental",
  "path": "/production/equipment/cameras",
  "totals": {
    "estimate": 25000,
    "actual": 22500,
    "variance": 2500
  },
  "tags": [
    "Day-1",
    "A-Camera",
    "Equipment"
  ],
  "contact": {
    "id": "contact-studio-001",
    "contactTitle": "Sunset Studios - Production Company",
    "name": "Alex Rivera",
    "email": "alex.rivera@sunsetstudios.com",
    "company": "Sunset Studios Inc.",
    "type": "Person",
    "jobTitle": "Director of Photography",
    "rate": 150,
    "secureInfo": { … },
    "origin": { … },
    "startwork": [ … ],
    "linkedUser": { … },
    "bankInfo": [ … ],
    "taxDocuments": [ … ],
    "attachments": [ … ],
    "projects": { … }
  },
  "phaseData": {
    "property1": { … },
    "property2": { … }
  }
}

Budget - Accounts

List all the budget accounts with children (i.e. Expanded Accounts)

Operations

Budget - Phases

Manage multiple budget versions (estimate, working, actual, committed).
Create rollup phases to auto-calculate variances.
Each phase supports its own currency.
Reference by name (e.g., "estimate") with idMode=user.

Operations

Budget - Fringes

Define payroll taxes and benefits (FICA, insurance, workers comp, etc.) once,
then auto-apply to all labor line items. Supports % or flat rates with salary cutoffs.

Operations

Budget - Globals

Set project-wide variables (e.g., exchange rates, shoot days, overhead %)
for use in formulas. Updating globals auto-recalculates dependent lines.

Operations

Actuals

Log real expenses from credit cards, manual entry, or converted POs.
Use expands[]=contact&expands[]=attachments to include contact details and receipts.
Split costs across multiple budget categories.

Operations

Purchase Orders

Create commitments to contacts/vendors before they become actuals.
Track approvals, link to budget lines, and monitor committed vs actual spend.
Convert POs to actuals when invoiced.

Operations

Tags

Categorize beyond account structure—e.g., by shoot day, location, department.
Use tags to run cross-budget reports and track spend across multiple categories.

Operations

Files

Upload receipts, contracts, and documents.
Attach files to actuals, POs, and projects.
Supports batch uploads and direct URL access.

Operations

Public Rates

Browse and use verified industry rate cards from the Saturation community.
Great for starting points or pricing validation.
Read-only access to rates from production companies, unions, and contractors.

Operations

Spaces

Group projects into folders for better organization.
Supports nested hierarchies (e.g., by client, year, or production type).

Operations

Comments

Add notes and discussions directly on budget lines.
Track approvals and changes with timestamps—context stays intact across phases.

Operations