# List transactions

Retrieve financial transactions with comprehensive filtering

Endpoint: GET /transactions
Version: 1.0.0
Security: ApiKeyAuth

## Query parameters:

  - `type` (array)
    Filter by transaction type
    Enum: "bank.deposit", "bank.withdrawal", "bank.ach", "bank.wire", "card.spend", "card.payment", "card.dispute", "card.refund", "card.cashback"

  - `status` (array)
    Filter by transaction status
    Enum: "posted", "pending", "void"

  - `subStatus` (array)
    Filter by transaction sub-status
    Enum: "settled", "refund", "reverse", "rejected"

  - `projectId` (any)
    Filter by project ID(s)
    Example: ["nike-swoosh-commercial"]

  - `sourceType` (any)
    Filter by source type
    Example: ["card"]

  - `sourceName` (any)
    Filter by source name
    Example: ["Amex 001"]

  - `sourceLast4` (any)
    Filter by source last 4 digits
    Example: ["4242"]

  - `description` (string)
    Filter by transaction description
    Example: "Camera rental"

  - `merchant` (string)
    Filter by merchant name
    Example: "B&H Photo"

  - `contactTitle` (string)
    Filter by contact title
    Example: "Producer"

  - `hasAccount` (boolean)
    Filter by account assignment
    Example: true

  - `isActualized` (boolean)
    Filter by actualization status

  - `hasAttachments` (boolean)
    Filter by whether attachments are present
    Example: true

  - `hasContact` (boolean)
    Filter by contact presence
    Example: true

  - `startDate` (string)
    Return results on or after this date (ISO 8601)
    Example: "2024-01-01"

  - `endDate` (string)
    Return results on or before this date (ISO 8601)
    Example: "2024-01-31"

  - `expands` (array)
    Include related data in the response
    Enum: "project", "contact", "account", "actual", "attachments"

  - `idMode` (string)
    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.
    Enum: "user", "system"

## Response 200 fields (application/json):

  - `transactions` (array)

  - `transactions.id` (string, required)
    Transaction identifier
    Example: "txn-abc-123"

  - `transactions.type` (string, required)
    Transaction type
    Enum: "bank.deposit", "bank.withdrawal", "bank.ach", "bank.wire", "card.spend", "card.payment", "card.dispute", "card.refund", "card.cashback"

  - `transactions.status` (string, required)
    Transaction status
    Enum: "posted", "pending", "void"

  - `transactions.subStatus` (string,null)
    Transaction sub-status
    Enum: "settled", "refund", "reverse", "rejected"

  - `transactions.description` (string, required)
    Transaction description
    Example: "ARRI RENTAL HOUSE"

  - `transactions.amount` (number, required)
    Transaction amount
    Example: 599.88

  - `transactions.date` (string, required)
    Transaction date
    Example: "2024-03-18T16:00:00Z"

  - `transactions.projectId` (string,null)
    Associated project ID
    Example: "nike-swoosh-commercial"

  - `transactions.hasAccount` (boolean, required)
    Whether transaction has account assignment
    Example: true

  - `transactions.isActualized` (boolean, required)
    Whether transaction has been converted to actual

  - `transactions.source` (object)

  - `transactions.source.id` (string, required)
    Source identifier
    Example: "src-card-001"

  - `transactions.source.type` (string, required)
    Source type (bank, card, etc.)
    Example: "card"

  - `transactions.source.name` (string, required)
    Source name
    Example: "Production Company Card"

  - `transactions.source.last4` (string, required)
    Last 4 digits of source identifier
    Example: "4242"

  - `transactions.attachments` (array)
    Attached files

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

  - `transactions.attachments.name` (string, required)
    Original filename
    Example: "call-sheet-day-3.pdf"

  - `transactions.attachments.type` (string, required)
    MIME type
    Example: "application/pdf"

  - `transactions.attachments.size` (integer, required)
    File size in bytes
    Example: 1048576

  - `transactions.contact` (object)

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

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

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

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

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

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

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

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

  - `transactions.contact.secureInfo` (object)

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

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

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

  - `transactions.contact.origin` (object)

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

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

  - `transactions.contact.origin.createdByUser` (object)

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

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

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

  - `transactions.contact.startwork` (array)
    Startwork agreements

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

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

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

  - `transactions.contact.linkedUser` (object)

  - `transactions.contact.bankInfo` (array)
    Banking information

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

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

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

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

  - `transactions.contact.taxDocuments` (array)
    Tax documents

  - `transactions.contact.attachments` (array)
    File attachments

  - `transactions.contact.projects` (object)
    Associated projects

  - `transactions.project` (object)

  - `transactions.project.id` (string, required)
    Project identifier (alias in user mode, UUID in system mode)
    Example: "nike-swoosh-commercial"

  - `transactions.project.name` (string,null)
    Project display name
    Example: "Nike Swoosh Commercial"

  - `transactions.project.icon` (string,null)
    Project icon or emoji
    Example: "☀️"

  - `transactions.project.imageUrl` (string,null)
    Project image URL
    Example: "https://example.com/project-banner.jpg"

  - `transactions.project.spaceId` (string,null)
    Associated project space ID (deprecated, use space object)
    Example: "commercial-productions"

  - `transactions.project.space` (object,null)
    Project space/folder information

  - `transactions.project.space.id` (string)
    Space identifier
    Example: "commercial-productions"

  - `transactions.project.space.name` (string)
    Space display name
    Example: "Commercial Productions"

  - `transactions.project.templateId` (string,null)
    Template project ID (deprecated, use template object)
    Example: "commercial-template"

  - `transactions.project.template` (object,null)
    Template project information

  - `transactions.project.template.id` (string)
    Template identifier
    Example: "commercial-template"

  - `transactions.project.template.name` (string)
    Template name
    Example: "Commercial Template"

  - `transactions.project.status` (string, required)
    Project status
    Enum: "active", "archived"

  - `transactions.project.labels` (array)
    Project labels for categorization
    Example: ["nike","q2-2024","post-production"]

  - `transactions.project.createdAt` (string, required)
    Project creation timestamp
    Example: "2024-01-15T10:00:00Z"

  - `transactions.project.updatedAt` (string, required)
    Project last update timestamp
    Example: "2024-03-20T14:30:00Z"

  - `transactions.account` (object)

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

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

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

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

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

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

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

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

  - `transactions.actual` (object)

  - `transactions.actual.id` (string, required)
    Actual entry identifier
    Example: "actual-001"

  - `transactions.actual.description` (string,null)
    Actual entry description
    Example: "Camera rental for shoot days"

  - `transactions.actual.amount` (number,null)
    Actual amount
    Example: 5250

  - `transactions.actual.date` (string,null)
    Actual entry date
    Example: "2024-03-15T12:00:00Z"

  - `transactions.actual.accountId` (any)
    Associated account ID(s)

  - `transactions.actual.expanded` (boolean, required)
    Whether this actual has sub-actuals

  - `transactions.actual.type` (string)
    Actual entry type
    Example: "invoice"

  - `transactions.actual.ref` (string,null)
    Reference identifier
    Example: "INV-2024-0315"

  - `transactions.actual.payId` (string,null)
    Payment identifier
    Example: "pay-xyz-789"

  - `transactions.actual.status` (string)
    Actual entry status
    Example: "completed"

  - `transactions.actual.notes` (string,null)
    Additional notes
    Example: "Q1 advertising budget"

  - `transactions.actual.tags` (array)
    Associated tags

  - `transactions.actual.purchaseOrderId` (string,null)
    Associated purchase order ID
    Example: "po-2024-001"

  - `transactions.actual.transactionId` (string,null)
    Associated transaction ID
    Example: "txn-abc-123"

  - `transactions.actual.subactuals` (array)
    Sub-actual entries

  - `transactions.actual.subactuals.id` (string, required)
    Sub-actual identifier
    Example: "subactual-001"

  - `transactions.actual.subactuals.description` (string,null)
    Sub-actual description
    Example: "Lighting equipment rental"

  - `transactions.actual.subactuals.amount` (number, required)
    Sub-actual amount
    Example: 2500

  - `transactions.actual.subactuals.date` (string,null)
    Sub-actual date
    Example: "2024-03-10T09:00:00Z"

  - `transactions.actual.subactuals.accountId` (string,null)
    Associated account ID
    Example: "/marketing/social-media"

## 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 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"