Skip to content

⚒️ API Reference (1.0.1)

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

List contacts

Request

Retrieve contacts with optional filtering

Security
ApiKeyAuth
Query
projectIdstring or Array of strings
Example: projectId=nike-swoosh-commercial
One of:
string
accountIdstring or Array of strings
Example: accountId=2150
One of:
string
originArray of strings

Filter by how the contact was created

Items Enum"onboarding""manual""api"
Example: origin=manual
hasLinkedUserboolean

Filter by linked user presence

hasAttachmentsboolean

Filter by whether attachments are present

Example: hasAttachments=true
hasTaxDocumentsboolean

Filter by tax document presence

Example: hasTaxDocuments=true
emailstring

Filter by email (case-insensitive partial match)

Example: email=producer@saturation.io
titlestring

Filter by title (case-insensitive partial match)

Example: title=Producer
expandsArray of strings

Fields to expand in the contact response. Expansions load additional related data on demand:

  • secureInfo: Contact's secure/private information (address, phone, tax ID last4)
  • origin: Creation source, timestamp, and user
  • projects: Associated projects keyed by alias (user mode) or ID (system mode)
  • projects.accounts: Project account breakdowns (requires including projects)
  • startwork: Startwork agreements and signature metadata
  • taxDocuments: W-9/1099 files linked to the contact
  • attachments: General attachments uploaded to the contact
  • bankInfo: Banking details sourced from Stripe/Plaid
  • linkedUser: Workspace user linked to the contact
Items Enum"secureInfo""origin""projects""projects.accounts""startwork""taxDocuments""attachments""bankInfo""linkedUser"
Example: expands=projects&expands=projects.accounts&expands=attachments
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/contacts?projectId=nike-swoosh-commercial&accountId=2150&origin=manual&hasLinkedUser=true&hasAttachments=true&hasTaxDocuments=true&email=producer%40saturation.io&title=Producer&expands=projects%2Cprojects.accounts%2Cattachments&idMode=user' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

List of contacts

Bodyapplication/json
contactsArray of objects(Contact)
Response
application/json
{
  "contacts": [
    { … }
  ]
}

Create contact

Request

Create a new contact

Security
ApiKeyAuth
Query
expandsArray of strings

Fields to expand in the contact response. Expansions load additional related data on demand:

  • secureInfo: Contact's secure/private information (address, phone, tax ID last4)
  • origin: Creation source, timestamp, and user
  • projects: Associated projects keyed by alias (user mode) or ID (system mode)
  • projects.accounts: Project account breakdowns (requires including projects)
  • startwork: Startwork agreements and signature metadata
  • taxDocuments: W-9/1099 files linked to the contact
  • attachments: General attachments uploaded to the contact
  • bankInfo: Banking details sourced from Stripe/Plaid
  • linkedUser: Workspace user linked to the contact
Items Enum"secureInfo""origin""projects""projects.accounts""startwork""taxDocuments""attachments""bankInfo""linkedUser"
Example: expands=projects&expands=projects.accounts&expands=attachments
Bodyapplication/jsonrequired
contactTitlestring

Display title or label shown in lists

Example: "Sunset Studios - Production Company"
namestringrequired

Contact name

Example: "Sunset Studios"
emailstring

Contact email address

Example: "contact@sunsetstudios.com"
companystring

Company name

Example: "Sunset Studios Inc."
typestring

Contact classification

Enum"Contractor""Employee""Company"
Example: "Contractor"
jobTitlestring

Job title

Example: "Production Coordinator"
ratenumber(float)

Hourly rate

Example: 125
phonestring

Phone number

Example: "310-555-1234"
addressstring

Physical address

Example: "123 Sunset Blvd, Los Angeles, CA 90028"
taxIdstring

Tax identifier (SSN/EIN). Stored securely; only the last four digits are returned.

Example: "123-45-6789"
paymentAccountArray of objects(ContactBankAccountCreate)

Optional bank accounts to add during creation

curl -i -X POST \
  'https://api.saturation.io/api/v1/contacts?expands=projects%2Cprojects.accounts%2Cattachments' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "contactTitle": "Sunset Studios - Production Company",
    "name": "Sunset Studios",
    "email": "contact@sunsetstudios.com",
    "company": "Sunset Studios Inc.",
    "type": "Contractor",
    "jobTitle": "Production Coordinator",
    "rate": 125,
    "phone": "310-555-1234",
    "address": "123 Sunset Blvd, Los Angeles, CA 90028",
    "taxId": "123-45-6789",
    "paymentAccount": [
      {
        "accountHolderType": "individual",
        "accountType": "checking",
        "routingNumber": "021000021",
        "accountNumber": "987654321"
      }
    ]
  }'

Responses

Contact created successfully

Bodyapplication/json
idstringrequired

Contact identifier

Example: "contact-studio-001"
contactTitlestring or null

Contact display title

Example: "Sunset Studios - Production Company"
namestring or null

Contact name

Example: "Alex Rivera"
emailstring or null

Contact email address

Example: "alex.rivera@sunsetstudios.com"
companystring or null

Contact company

Example: "Sunset Studios Inc."
typestring or null

Contact classification

Enum"Contractor""Employee""Company"
Example: "Contractor"
jobTitlestring or null

Contact job title

Example: "Director of Photography"
ratenumber or null(float)

Contact hourly rate

Example: 150
lastModifiedstring(date-time)required

Last modification time (ISO 8601)

Example: "2024-03-15T14:30:00Z"
secureInfoobject
originobject
startworkArray of objects(ContactStartwork)

Returned when expands includes startwork.

linkedUserobject or null
bankInfoArray of objects or null(ContactBankAccount)

Stripe/Plaid banking sources. Returned when expands includes bankInfo.

taxDocumentsArray of objects(File)

Returned when expands includes taxDocuments.

attachmentsArray of objects(File)

Returned when expands includes attachments.

projectsobject

Associated projects keyed by project alias (idMode=user) or ID (idMode=system). Returned when expands includes projects.

Response
application/json
{
  "id": "contact-studio-001",
  "contactTitle": "Sunset Studios - Production Company",
  "name": "Alex Rivera",
  "email": "alex.rivera@sunsetstudios.com",
  "company": "Sunset Studios Inc.",
  "type": "Contractor",
  "jobTitle": "Director of Photography",
  "rate": 150,
  "lastModified": "2024-03-15T14:30:00Z",
  "secureInfo": {
    "address": "123 Sunset Blvd, Los Angeles, CA 90028",
    "phone": "310-555-1234",
    "taxIdLast4": "4567"
  },
  "origin": {
    "origin": "manual",
    "createdAt": "2024-02-15T08:00:00Z",
    "createdByUser": { … }
  },
  "startwork": [
    { … }
  ],
  "linkedUser": {
    "id": "user-001",
    "name": "Sarah Chen",
    "email": "sarah.chen@sunsetstudios.com"
  },
  "bankInfo": [
    { … }
  ],
  "taxDocuments": [
    { … }
  ],
  "attachments": [
    { … }
  ],
  "projects": {
    "property1": { … },
    "property2": { … }
  }
}

Get contact

Request

Retrieve a specific contact by ID or alias

Security
ApiKeyAuth
Path
contactIdstringrequired

Contact identifier (alias or ID)

Example: contact-studio-001
Query
expandsArray of strings

Fields to expand in the contact response. Expansions load additional related data on demand:

  • secureInfo: Contact's secure/private information (address, phone, tax ID last4)
  • origin: Creation source, timestamp, and user
  • projects: Associated projects keyed by alias (user mode) or ID (system mode)
  • projects.accounts: Project account breakdowns (requires including projects)
  • startwork: Startwork agreements and signature metadata
  • taxDocuments: W-9/1099 files linked to the contact
  • attachments: General attachments uploaded to the contact
  • bankInfo: Banking details sourced from Stripe/Plaid
  • linkedUser: Workspace user linked to the contact
Items Enum"secureInfo""origin""projects""projects.accounts""startwork""taxDocuments""attachments""bankInfo""linkedUser"
Example: expands=projects&expands=projects.accounts&expands=attachments
curl -i -X GET \
  'https://api.saturation.io/api/v1/contacts/contact-studio-001?expands=projects%2Cprojects.accounts%2Cattachments' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Contact details

Bodyapplication/json
idstringrequired

Contact identifier

Example: "contact-studio-001"
contactTitlestring or null

Contact display title

Example: "Sunset Studios - Production Company"
namestring or null

Contact name

Example: "Alex Rivera"
emailstring or null

Contact email address

Example: "alex.rivera@sunsetstudios.com"
companystring or null

Contact company

Example: "Sunset Studios Inc."
typestring or null

Contact classification

Enum"Contractor""Employee""Company"
Example: "Contractor"
jobTitlestring or null

Contact job title

Example: "Director of Photography"
ratenumber or null(float)

Contact hourly rate

Example: 150
lastModifiedstring(date-time)required

Last modification time (ISO 8601)

Example: "2024-03-15T14:30:00Z"
secureInfoobject
originobject
startworkArray of objects(ContactStartwork)

Returned when expands includes startwork.

linkedUserobject or null
bankInfoArray of objects or null(ContactBankAccount)

Stripe/Plaid banking sources. Returned when expands includes bankInfo.

taxDocumentsArray of objects(File)

Returned when expands includes taxDocuments.

attachmentsArray of objects(File)

Returned when expands includes attachments.

projectsobject

Associated projects keyed by project alias (idMode=user) or ID (idMode=system). Returned when expands includes projects.

Response
application/json
{
  "id": "contact-studio-001",
  "contactTitle": "Sunset Studios - Production Company",
  "name": "Alex Rivera",
  "email": "alex.rivera@sunsetstudios.com",
  "company": "Sunset Studios Inc.",
  "type": "Contractor",
  "jobTitle": "Director of Photography",
  "rate": 150,
  "lastModified": "2024-03-15T14:30:00Z",
  "secureInfo": {
    "address": "123 Sunset Blvd, Los Angeles, CA 90028",
    "phone": "310-555-1234",
    "taxIdLast4": "4567"
  },
  "origin": {
    "origin": "manual",
    "createdAt": "2024-02-15T08:00:00Z",
    "createdByUser": { … }
  },
  "startwork": [
    { … }
  ],
  "linkedUser": {
    "id": "user-001",
    "name": "Sarah Chen",
    "email": "sarah.chen@sunsetstudios.com"
  },
  "bankInfo": [
    { … }
  ],
  "taxDocuments": [
    { … }
  ],
  "attachments": [
    { … }
  ],
  "projects": {
    "property1": { … },
    "property2": { … }
  }
}

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

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