# Create budget lines

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  to add lines at the top level of your budget.


Endpoint: POST /projects/{projectId}/budget
Version: 1.0.0
Security: ApiKeyAuth

## Path parameters:

  - `projectId` (string, required)
    Project identifier (alias or ID)
    Example: "nike-spring-2024"

## Request fields (application/json):

  - `accountId` (string)
    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"

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

  - `lines.type` (string)
    Type of budget line
    Enum: "line", "account", "subtotal", "markup"

  - `lines.accountId` (string)
    Account code or ID
    Example: "2150"

  - `lines.description` (string)
    Line description
    Example: "Camera Equipment Rental"

  - `lines.phaseData` (object)
    Phase-specific data

  - `insert` (object)
    Where to insert the new lines

  - `insert.mode` (string)
    Enum: "append", "prepend", "after", "before"

  - `insert.lineId` (string)
    Line ID for after/before mode
    Example: "line-001"

  - `idMode` (string)
    ID interpretation mode - "user" for human-friendly IDs (default), "system" for database IDs
    Enum: "user", "system"

## Response 201 fields (application/json):

  - `account` (object, required)

  - `account.id` (string, required)
    Account system identifier
    Example: "acc-xyz-789"

  - `account.accountId` (string,null)
    User-friendly account code/number
    Example: "2150"

  - `account.description` (string,null)
    Account description
    Example: "Camera Equipment"

  - `account.path` (string, required)
    Hierarchical path in budget tree
    Example: "/production/equipment"

  - `account.lines` (array, required)
    Budget lines within this account

  - `account.lines.type` (string, required)
    Type of budget line
    Enum: "line", "account", "subtotal", "markup", "fringes"

  - `account.lines.id` (string, required)
    Budget line identifier (system ID)
    Example: "line-001"

  - `account.lines.accountId` (string,null)
    Account identifier (user-friendly ID like account code)
    Example: "2150"

  - `account.lines.description` (string,null)
    Budget line description
    Example: "RED Camera Package Rental"

  - `account.lines.path` (string, required)
    Hierarchical path in budget tree (e.g., /2000/2150)
    Example: "/production/equipment/cameras"

  - `account.lines.totals` (object, required)
    Calculated totals for each phase
    Example: {"estimate":25000,"actual":22500,"variance":2500}

  - `account.lines.tags` (array)
    Tags for categorization and filtering
    Example: ["Day-1","A-Camera","Equipment"]

  - `account.lines.contact` (object)

  - `account.lines.contact.id` (string, required)
    Contact identifier
    Example: "contact-studio-001"

  - `account.lines.contact.contactTitle` (string,null)
    Contact display title
    Example: "Sunset Studios - Production Company"

  - `account.lines.contact.name` (string,null)
    Contact name
    Example: "Alex Rivera"

  - `account.lines.contact.email` (string,null)
    Contact email address
    Example: "alex.rivera@sunsetstudios.com"

  - `account.lines.contact.company` (string,null)
    Contact company
    Example: "Sunset Studios Inc."

  - `account.lines.contact.type` (string,null)
    Contact type (Person, Company, etc.)
    Example: "Person"

  - `account.lines.contact.jobTitle` (string,null)
    Contact job title
    Example: "Director of Photography"

  - `account.lines.contact.rate` (number,null)
    Contact hourly rate
    Example: 150

  - `account.lines.contact.secureInfo` (object)

  - `account.lines.contact.secureInfo.address` (string,null)
    Contact address
    Example: "123 Sunset Blvd, Los Angeles, CA 90028"

  - `account.lines.contact.secureInfo.phone` (string,null)
    Contact phone number
    Example: "310-555-1234"

  - `account.lines.contact.secureInfo.taxIdLast4` (string,null)
    Last 4 digits of tax ID
    Example: "4567"

  - `account.lines.contact.origin` (object)

  - `account.lines.contact.origin.origin` (string,null)
    How the contact was created
    Enum: "onboarding", "manual"

  - `account.lines.contact.origin.createdAt` (string,null)
    Contact creation timestamp
    Example: "2024-02-15T08:00:00Z"

  - `account.lines.contact.origin.createdByUser` (object)

  - `account.lines.contact.origin.createdByUser.id` (string, required)
    User identifier
    Example: "user-001"

  - `account.lines.contact.origin.createdByUser.name` (string, required)
    User name
    Example: "Sarah Chen"

  - `account.lines.contact.origin.createdByUser.email` (string, required)
    User email address
    Example: "sarah.chen@sunsetstudios.com"

  - `account.lines.contact.startwork` (array)
    Startwork agreements

  - `account.lines.contact.startwork.id` (string, required)
    Startwork agreement identifier
    Example: "startwork-001"

  - `account.lines.contact.startwork.title` (string, required)
    Agreement title
    Example: "Independent Contractor Agreement"

  - `account.lines.contact.startwork.signedOn` (string, required)
    Signature timestamp
    Example: "2024-03-01T10:00:00Z"

  - `account.lines.contact.linkedUser` (object)

  - `account.lines.contact.bankInfo` (array)
    Banking information

  - `account.lines.contact.bankInfo.id` (string, required)
    Bank account identifier
    Example: "bank-acc-001"

  - `account.lines.contact.bankInfo.bankName` (string, required)
    Bank name
    Example: "Chase Bank"

  - `account.lines.contact.bankInfo.accountType` (string, required)
    Account type (checking, savings, etc.)
    Example: "checking"

  - `account.lines.contact.bankInfo.accountLast4` (string, required)
    Last 4 digits of account number
    Example: "4567"

  - `account.lines.contact.taxDocuments` (array)
    Tax documents

  - `account.lines.contact.taxDocuments.id` (string, required)
    File identifier (DigitalOcean Spaces object key)
    Example: "files/2024/03/budget-report.pdf"

  - `account.lines.contact.taxDocuments.name` (string, required)
    Original filename
    Example: "call-sheet-day-3.pdf"

  - `account.lines.contact.taxDocuments.type` (string, required)
    MIME type
    Example: "application/pdf"

  - `account.lines.contact.taxDocuments.size` (integer, required)
    File size in bytes
    Example: 1048576

  - `account.lines.contact.attachments` (array)
    File attachments

  - `account.lines.contact.projects` (object)
    Associated projects

  - `account.lines.phaseData` (object)
    Detailed phase-specific data (expandable)

  - `subAccounts` (object)
    Sub-account hierarchy

  - `phases` (array)
    Budget phases

  - `phases.type` (string, required)
    Phase type
    Enum: "estimate", "actual", "rollup", "committed"

  - `phases.id` (string, required)
    Phase system identifier
    Example: "phase-001"

  - `phases.alias` (string, required)
    User-friendly phase alias
    Example: "estimate"

  - `phases.name` (string,null)
    Phase display name
    Example: "Initial Estimate"

  - `phases.isHidden` (boolean, required)
    Whether phase is hidden from view

  - `phases.isLocked` (boolean, required)
    Whether phase is locked from editing

  - `phases.currency` (object,null)
    Currency configuration (for estimate phases)

  - `phases.currency.code` (string,null)
    ISO 4217 currency code
    Example: "USD"

  - `phases.currency.symbol` (string,null)
    Currency symbol
    Example: "$"

  - `phases.currency.exchangeRate` (number,null)
    Exchange rate multiplier
    Example: 1

  - `phases.operation` (string)
    Rollup operation (for rollup phases)
    Enum: "sum", "difference"

  - `phases.phaseIds` (array)
    Phase IDs to aggregate (for rollup phases)
    Example: ["estimate","actual"]

  - `fringes` (array)
    Fringe benefits

  - `fringes.id` (string, required)
    Fringe system identifier
    Example: "fringe-001"

  - `fringes.code` (string,null)
    User-friendly fringe code
    Example: "FICA"

  - `fringes.description` (string,null)
    Fringe benefit description
    Example: "Social Security Tax"

  - `fringes.units` (string, required)
    Fringe calculation units
    Enum: "percent", "flat"

  - `fringes.rate` (number,null)
    Fringe rate (decimal for percent, amount for flat)
    Example: 0.0765

  - `fringes.cutoff` (number,null)
    Maximum salary subject to this fringe
    Example: 160200

  - `globals` (array)
    Global variables

  - `globals.id` (string, required)
    Global variable system identifier
    Example: "global-001"

  - `globals.symbol` (string,null)
    Variable symbol for use in formulas
    Example: "EXCHANGE_RATE"

  - `globals.description` (string,null)
    Variable description
    Example: "USD to EUR exchange rate"

  - `globals.unit` (string,null)
    Unit of measurement
    Example: "currency"

  - `globals.formula` (string,null)
    Formula expression for calculating value
    Example: "1.08"

## Response 400 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (object)
    Additional error details
    Example: {"field":"projectId","reason":"Project not found"}

  - `code` (string)
    Error code
    Example: "VALIDATION_ERROR"

## Response 401 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (object)
    Additional error details
    Example: {"field":"projectId","reason":"Project not found"}

  - `code` (string)
    Error code
    Example: "VALIDATION_ERROR"

## Response 404 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (object)
    Additional error details
    Example: {"field":"projectId","reason":"Project not found"}

  - `code` (string)
    Error code
    Example: "VALIDATION_ERROR"

## Response 500 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (object)
    Additional error details
    Example: {"field":"projectId","reason":"Project not found"}

  - `code` (string)
    Error code
    Example: "VALIDATION_ERROR"