Notice of Deprecation of Fields and Objects (Nov 2025)

November 7, 2025

Deprecated Fields, Objects & List Options

This document provides a comprehensive breakdown of all deprecated fields in the Unified API as of November 2025, organized by category with migration recommendations.

Please make all necessary changes to your code by JANUARY 7, 2026

MetadataMetadata Fields

Field: `key` → `slug`

Affected Models:

IKmsPageMetadata (KMS) - src/models/UnifiedKms.ts
ITaskMetadata (Task) - src/models/UnifiedTask.ts
IHrisMetadata (HRIS) - src/models/UnifiedHris.ts
IAtsMetadata (ATS) - src/models/UnifiedAts.ts
ICommerceMetadata (Commerce) - src/models/UnifiedCommerce.ts
ICrmMetadata (CRM) - src/models/UnifiedCrm.ts

Deprecated Field:

key?: string; // @deprecated; use slug instead

Replacement:

slug?: string; // Actual textual value of the slug

Migration Recommendation:

Read Operations: Replace all references to metadata.key with metadata.slug
Write Operations: Use slug instead of key when creating or updating metadata objects

Example:

// Before
metadata: [{
    key: "custom_field",
    value: "some value"
}]

// After
metadata: [{
    slug: "custom_field",
    value: "some value"
}]

Field: `type` → `format`

Affected Models:

IKmsPageMetadata (KMS) - src/models/UnifiedKms.ts
ITaskMetadata (Task) - src/models/UnifiedTask.ts
IHrisMetadata (HRIS) - src/models/UnifiedHris.ts
IAtsMetadata (ATS) - src/models/UnifiedAts.ts
ICommerceMetadata (Commerce) - src/models/UnifiedCommerce.ts
ICrmMetadata (CRM) - src/models/UnifiedCrm.ts

Deprecated Field:

type?: string; // @deprecated; use format instead

Replacement:

format?: TMetadataFormat; // Enum: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL, etc.

Migration Recommendation:

Read Operations: Replace all references to metadata.type with metadata.format
Write Operations: Use format with the appropriate enum value instead of type string
Type Safety: The format field uses strongly-typed enums, providing better type safety and validation

Example:

// Before
metadata: [{
    key: "age",
    type: "number",
    value: 25
}]

// After
metadata: [{
    slug: "age",
    format: "NUMBER", // Use enum value
    value: 25
}]

Parent Fields

Field: `parent_space_id` → `parent_id`

Field: `parent_page_id` → `parent_id`

Affected Models:

IKmsSpace - src/models/UnifiedKms.ts
IKmsPage - src/models/UnifiedKms.ts

Deprecated Field:

// In KmsSpace
parent_space_id?: string; // @deprecated; use parent_id instead

// In KmsPage
parent_page_id?: string; // @deprecated; use parent_id instead

Replacement:

parent_id?: string;

Migration Recommendation:

Read Operations: Use parent_id instead of parent_space_id when reading space objects
Write Operations: Use parent_id when creating or updating spaces

Example:

// Before
const space = {
    name: "Subspace",
    parent_space_id: "space_123"
}

// After
const space = {
    name: "Subspace",
    parent_id: "space_123"
}

Field: `parent_channel_id` → `parent_id`

Affected Model:

IMessagingChannel - src/models/UnifiedMessaging.ts

Deprecated Field:

parent_channel_id?: string; // @deprecated; use parent_id instead

Replacement:

parent_id?: string;

Migration Recommendation:

Read Operations: Use parent_id instead of parent_channel_id when reading channel objects
Write Operations: Use parent_id when creating or updating channels

Example:

// Before
const channel = {
    name: "Sub-channel",
    parent_channel_id: "channel_123"
}

// After
const channel = {
    name: "Sub-channel",
    parent_id: "channel_123"
}

Field: `parent_account_id` → `parent_id`

Affected Model:

IAccountingAccount

Deprecated Field:

parent_account_id?: string; // @deprecated; use parent_id instead

Replacement:

parent_id?: string; // The parent account ID for this account

Migration Recommendation:

Read Operations: Use parent_id instead of parent_account_id when reading account objects
Write Operations: Use parent_id when creating or updating accounts

Example:

// Before
const account = {
    name: "Sub-account",
    parent_account_id: "account_123"
}

// After
const account = {
    name: "Sub-account",
    parent_id: "account_123"
}

Field: `parent_message_id` → `parent_id`

Affected Model:

IMessagingMessage

Deprecated Field:

parent_message_id?: string; // @deprecated; use parent_id

Replacement:

parent_id?: string; // Represents the ID of the immediate predecessor message in the thread

Migration Recommendation:

Read Operations: Use parent_id instead of parent_message_id when reading message objects
Write Operations: Use parent_id when creating threaded messages

Example:

// Before
const message = {
    message: "Reply text",
    parent_message_id: "msg_123"
}

// After
const message = {
    message: "Reply text",
    parent_id: "msg_123"
}

HRIS Employee Fields

Field: `department` → `groups`

Affected Model:

IHrisEmployee - src/models/UnifiedHris.ts

Deprecated Field:

department?: string; // @deprecated

Replacement:

groups?: IHrisGroup[]; // Which groups/teams/units that this employee/user belongs to

Migration Recommendation:

Read Operations: Access department information through the groups array
Write Operations: Use groups array with IHrisGroup objects instead of a single department string
Multiple Groups: The groups field supports multiple group memberships, which is more flexible than a single department

Example:

// Before
const employee = {
    name: "John Doe",
    department: "Engineering"
}

// After
const employee = {
    name: "John Doe",
    groups: [{
        id: "group_123",
        name: "Engineering",
        type: "DEPARTMENT"
    }]
}

Field:`division` → `groups`

Affected Model:

IHrisEmployee

Deprecated Field:

division?: string; // @deprecated

Replacement:

groups?: IHrisGroup[]; // Which groups/teams/units that this employee/user belongs to

Migration Recommendation:

Read Operations: Access division information through the groups array
Write Operations: Use groups array with IHrisGroup objects instead of a single division string

Example:

// Before
const employee = {
    name: "John Doe",
    division: "Product"
}

// After
const employee = {
    name: "John Doe",
    groups: [{
        id: "group_456",
        name: "Product",
        type: "DIVISION"
    }]
}

Field: `location` → `locations`

Affected Model:

IHrisEmployee - src/models/UnifiedHris.ts

Deprecated Field:

location?: string; // @deprecated

Replacement:

locations?: IHrisLocation[]; // Array of partial location objects

Migration Recommendation:

Read Operations: Access location information through the locations array
Write Operations: Use locations array with IHrisLocation objects instead of a single location string
Rich Data: The locations array provides full address details, timezone, currency, and other metadata

Example:

// Before
const employee = {
    name: "John Doe",
    location: "San Francisco Office"
}

// After
const employee = {
    name: "John Doe",
    locations: [{
        id: "loc_123",
        name: "San Francisco Office",
        address: {
            address1: "123 Main St",
            city: "San Francisco",
            region: "CA",
            postal_code: "94102",
            country: "United States"
        },
        timezone: "America/Los_Angeles"
    }]
}

Messaging Fields

Field: `channel_id` → `channels`

Field: `channel_ids` → `channels`

Affected Model:

IMessagingMessage - src/models/UnifiedMessaging.ts

Deprecated Field:

channel_id?: string; // @deprecated

Replacement:

channels?: IMessagingChannelMessage[]; // Represents the names of all channels to which the message is sent / belongs to

Migration Recommendation:

Read Operations: Use channels array instead of channel_id or channels_ids
Write Operations: Use channels array when creating messages
Multi-Channel Support: The channels array supports messages posted to multiple channels (when the integration supports it)

Example:

// Before
const message = {
    message: "Hello",
    channel_id: "channel_123",
    channels_ids: ["channel_123"]
}

// After
const message = {
    message: "Hello",
    channels: [{
        id: "channel_123",
        name: "General"
    }]
}

Field: `root_message_id` → Removed

Affected Model:

IMessagingMessage

Deprecated Field:

root_message_id?: string; // @deprecated

Replacement:

No direct replacement. Use parent_id to traverse the thread structure.

Migration Recommendation:

Read Operations: If you need to find the root message, traverse the parent_id chain until you reach a message without a parent_id
Write Operations: Remove references to root_message_id when creating messages

Example:

// Before
const message = {
    message: "Reply",
    parent_message_id: "msg_123",
    root_message_id: "msg_1"
}

// After
const message = {
    message: "Reply",
    parent_id: "msg_123"
    // root_message_id removed - traverse parent_id chain if needed
}

// Helper function to find root message
function findRootMessage(message) {
    while (message.parent_id) {
        message = getMessage(message.parent_id);
    }
    return message;
}

Accounting Fields

Field: `invoice_at` → `posted_at`

Affected Model:

IAccountingInvoice

Deprecated Field:

invoice_at?: (string | Date | number); // @deprecated; use posted_at

Replacement:

posted_at?: (string | Date | number);

Migration Recommendation:

Read Operations: Use posted_at instead of invoice_at when reading invoice objects
Write Operations: Use posted_at when creating or updating invoices
Consistency: This change aligns with other accounting objects that use posted_at for transaction dates

Example:

// Before
const invoice = {
    invoice_number: "INV-001",
    invoice_at: "2024-01-15"
}

// After
const invoice = {
    invoice_number: "INV-001",
    posted_at: "2024-01-15"
}

Field: `type` → Removed

Affected Model:

IAccountingInvoice

Deprecated Field:

type?: TAccountingInvoiceType; // @deprecated

Replacement:

No direct replacement. Bills are now found in the AccountingBill object, while invoices are solely in the AccountingInvoice object.

Migration Recommendation:

Read Operations: Remove dependencies on invoice.type field
Alternative: Bills are now found in the AccountingBill object, while invoices are solely in the AccountingInvoice object.

Field: `contact_id` → `contacts`

Affected Model:

IAccountingTransaction - src/models/UnifiedAccounting.ts

Deprecated Field:

contact_id?: string; // @deprecated; use contacts

Replacement:

contacts?: IAccountingTransactionContact[];

Migration Recommendation:

Read Operations: Use contacts array instead of contact_id
Write Operations: Use contacts array when creating transactions, but just include an id field
Multi-Contact Support: The contacts array supports multiple contacts per transaction (when the integration supports multiple contacts)
Rich Data: Provides contact names and emails, not just IDs

Example:

// Before
const transaction = {
    total_amount: 1000,
    contact_id: "contact_123"
}

// After
const transaction = {
    total_amount: 1000,
    contacts: [{
        id: "contact_123",
        name: "Acme Corp",
        emails: [{
            email: "billing@acme.com"
        }]
    }]
}

Field: `income` → `income_sections`

Affected Model:

IAccountingProfitloss - src/models/UnifiedAccounting.ts

Deprecated Field:

income?: IAccountingProfitlossCategory[]; // @deprecated – use income_sections instead

Replacement:

income_sections?: IAccountingProfitlossSection[];

Migration Recommendation:

Read Operations: Use income_sections instead of income
Write Operations: Use income_sections when creating profit/loss reports
Enhanced Structure: The new income_sections provides a more structured format with better categorization

Example:

// Before
const profitloss = {
    start_at: "2024-01-01",
    end_at: "2024-12-31",
    income: [{
        name: "Sales",
        amount: 100000
    }]
}

// After
const profitloss = {
    start_at: "2024-01-01",
    end_at: "2024-12-31",
    income_sections: [{
        name: "Sales",
        accounts: [{
            name: "Product Sales",
            amount: 100000
        }]
    }]
}

Field:`expenses` → `expenses_sections`

Affected Model:

IAccountingProfitloss

Deprecated Field:

expenses?: IAccountingProfitlossCategory[]; // @deprecated – use expenses_sections instead

Replacement:

expenses_sections?: IAccountingProfitlossSection[];

Migration Recommendation:

Read Operations: Use expenses_sections instead of expenses
Write Operations: Use expenses_sections when creating profit/loss reports

Example:

// Before
const profitloss = {
    expenses: [{
        name: "Operating Expenses",
        amount: 50000
    }]
}

// After
const profitloss = {
    expenses_sections: [{
        name: "Operating Expenses",
        accounts: [{
            name: "Salaries",
            amount: 50000
        }]
    }]
}

Field:`cost_of_goods_sold` → `cost_of_goods_sold_sections`

Affected Model:

IAccountingProfitloss

Deprecated Field:

cost_of_goods_sold?: IAccountingProfitlossCategory[]; // @deprecated – use cost_of_goods_sold_sections instead

Replacement:

cost_of_goods_sold_sections?: IAccountingProfitlossSection[];

Migration Recommendation:

Read Operations: Use cost_of_goods_sold_sections instead of cost_of_goods_sold
Write Operations: Use cost_of_goods_sold_sections when creating profit/loss reports

Example:

// Before
const profitloss = {
    cost_of_goods_sold: [{
        name: "Materials",
        amount: 30000
    }]
}

// After
const profitloss = {
    cost_of_goods_sold_sections: [{
        name: "Materials",
        accounts: [{
            name: "Raw Materials",
            amount: 30000
        }]
    }]
}

Field:`gross_profit_amount` → Calculate from `income_total_amount` and `cost_of_goods_sold_total_amount`

Affected Model:

IAccountingProfitloss

Deprecated Field:

gross_profit_amount?: number; // @deprecated – compute using income_total_amount - cost_of_goods_sold_total_amount

Replacement:

gross_profit_amount = income_total_amount - cost_of_goods_sold_total_amount

Migration Recommendation:

Read Operations: Calculate gross_profit_amount using income_total_amount - cost_of_goods_sold_total_amount
Write Operations: Do not set gross_profit_amount directly

Example:

// Before
const profitloss = {
    income_total_amount: 100000,
    cost_of_goods_sold_total_amount: 30000,
    gross_profit_amount: 70000
}

// After
const profitloss = {
    income_total_amount: 100000,
    cost_of_goods_sold_total_amount: 30000
    // gross_profit_amount removed - calculate it
}

// Calculate gross profit
const gross_profit_amount = profitloss.income_total_amount - profitloss.cost_of_goods_sold_total_amount;

Field: `net_profit_amount` → `net_income_amount`

Affected Model:

IAccountingProfitloss

Deprecated Field:

net_profit_amount?: number; // @deprecated – use net_income_amount instead

Replacement:

net_income_amount?: number;

Migration Recommendation:

Read Operations: Use net_income_amount instead of net_profit_amount
Write Operations: Use net_income_amount when creating profit/loss reports

Example:

// Before
const profitloss = {
    net_profit_amount: 50000
}

// After
const profitloss = {
    net_income_amount: 50000
}

Field: `IAccountingProfitlossCategory` and `IAccountingProfitlossSubcategory` → Deprecated Types

Deprecated Types:

IAccountingProfitlossCategory - @deprecated
IAccountingProfitlossSubcategory - @deprecated

Replacement:

Use IAccountingProfitlossSection instead

Migration Recommendation:

Type Definitions: Update TypeScript interfaces to use IAccountingProfitlossSection
Read Operations: Use income_sections, expenses_sections, and cost_of_goods_sold_sections which use the new section structure

Example:

// Before
interface Profitloss {
    income?: IAccountingProfitlossCategory[];
}

// After
interface Profitloss {
    income_sections?: IAccountingProfitlossSection[];
}

ATS (Applicant Tracking System) Fields

Field:`document_id` → `document_ids`

Affected Model:

IAtsActivity - src/models/UnifiedAts.ts

Deprecated Field:

document_id?: string; // @deprecated

Replacement:

document_ids?: string[]; // IDs for AtsDocument.get

Migration Recommendation:

Read Operations: Use document_ids array instead of document_id
Write Operations: Use document_ids array when creating activities
Multi-Document Support: Supports multiple documents per activity

Example:

// Before
const activity = {
    title: "Review Resume",
    document_id: "doc_123"
}

// After
const activity = {
    title: "Review Resume",
    document_ids: ["doc_123", "doc_456"]
}

Field: `departments` → `groups`

Affected Model:

IAtsJob - src/models/UnifiedAts.ts

Deprecated Field:

departments?: string[]; // @deprecated Use `groups` instead

Replacement:

groups?: IAtsGroup[]; // The departments/divisions/teams that this job belongs to

Migration Recommendation:

Read Operations: Use groups array instead of departments
Write Operations: Use groups array with IAtsGroup objects instead of department strings
Rich Data: Provides group IDs, names, and types (TEAM, GROUP, DEPARTMENT, DIVISION, etc.)

Example:

// Before
const job = {
    name: "Software Engineer",
    departments: ["Engineering", "Product"]
}

// After
const job = {
    name: "Software Engineer",
    groups: [{
        id: "group_123",
        name: "Engineering",
        type: "DEPARTMENT"
    }, {
        id: "group_456",
        name: "Product",
        type: "DEPARTMENT"
    }]
}

Ticketing Fields

Field: `category` → `category_id`

Affected Model:

ITicketingTicket - src/models/UnifiedTicketing.ts

Deprecated Field:

category?: string; // @deprecated; use category_id

Replacement:

category_id?: string;

Migration Recommendation:

Read Operations: Use category_id instead of category string
Write Operations: Use category_id when creating or updating tickets
Consistency: Using category_id maintains consistency with other ID-based relationships

Example:

// Before
const ticket = {
    subject: "Support Request",
    category: "technical"
}

// After
const ticket = {
    subject: "Support Request",
    category_id: "category_123"
}

Query Parameters & Filters

`expand_recurring_events` → `expand`

Affected Models:

ICalendarEvent

Deprecated Parameter:

expand_recurring_events?: boolean; // @deprecated; use expand

Replacement:

expand?: boolean;

Migration Recommendation:

API Calls: Replace expand_recurring_events query parameter with expand
More Flexible: expand supports expanding multiple event types, not just recurring events

Example:

// Before
GET /api/calendar/events?expand_recurring_events=true

// After
GET /api/calendar/events?expand=true

`end_le` → `end_lt`

Affected Models:

ICalendarEvent
ICalendarBusy
ICalendarRecording
IUcCall
IUcRecording
IHrisTimeoff
IHrisTimeshift
IAccountingBalancesheet
IAccountingCashflow
IAccountingProfitloss
IAccountingTrialbalance
IMessagingMessage
IPaymentSubscription
IPaymentPayment
IPaymentPayout

Deprecated Parameter:

end_le?: string | Date; // @deprecated; use end_lt

Replacement:

end_lt?: string | Date;

Migration Recommendation:

API Calls: Replace end_le (less than or equal) with end_lt (less than)
Consistency: Aligns with standard date range filtering conventions

Example:

// Before
GET /api/calendar/events?end_le=2024-12-31

// After
GET /api/calendar/events?end_lt=2025-01-01
// Note: Adjust date by +1 day if you need inclusive end date



---


## Webhook Payload Fields


### Field: `sig` → `sig256`


**Affected Interface:**

- `IWebhookData`

**Deprecated Field:**


```typescript
sig?: string; // @deprecated; use sig256 instead

Replacement:

sig256?: string; // HMAC-SHA256(workspace.secret, data + nonce)

Migration Recommendation:

Webhook Verification: Use sig256 instead of sig for webhook signature verification
Security: sig256 uses HMAC-SHA256 which is more secure than the previous signature algorithm. sig used HMAC-SHA1, which is now deprecated.
Verification: Update your webhook verification code to check sig256 field

Example:

// Before
const isValid = verifySignature(webhook.sig, payload, secret, 'sha');

// After
const isValid = verifySignature(webhook.sig256, payload, secret, ‘sha256');



---


## Deprecated Objects/Usage Patterns


### `IAccountingInvoice` with `type === 'BILL'` → Use `IAccountingBill`


**Status:** Deprecated usage pattern:

- Instead of using `IAccountingInvoice` with `type='BILL'`, use the dedicated `IAccountingBill` object

**Affected Model:**

- `IAccountingInvoice` - `src/models/UnifiedAccounting.ts`

**Deprecated Pattern:**


```typescript
interface IAccountingInvoice {
  type: 'BILL',  // @deprecated - use IAccountingBill instead
  ...
}

Replacement:

interface IAccountingBill {
    ...
}

Key Differences:

IAccountingBill uses bill_number instead of invoice_number
IAccountingBill does not have the deprecated type field
IAccountingBill does not have the deprecated invoice_at field (uses posted_at instead)
More semantic clarity: a Bill is clearly distinct from an Invoice

Migration Recommendation:

Read Operations: Use accounting_bill endpoints instead of accounting_invoice endpoints with type='BILL'
Write Operations: Use accounting_bill create/update endpoints instead of accounting_invoice with type='BILL'

Field Mapping: When migrating data:

invoice_number → bill_number
Remove type field (no longer needed)
invoice_at → posted_at (if still using deprecated field)

API Endpoints:

❌ Deprecated: POST /accounting/invoice with type: 'BILL'
✅ Use: POST /accounting/bill

Example:

// Before
POST /accounting/invoice
{
    "type": "BILL",
    "invoice_number": "BILL-001",
    "contact_id": "contact_123",
    "total_amount": 1000
}

// After
POST /accounting/bill
{
    "bill_number": "BILL-001",
    "contact_id": "contact_123",
    "total_amount": 1000
}

`IAccountingReport` → Use Individual Report Objects

Status: Deprecated object

Instead of using IAccountingReport, use the individual report objects directly

Affected Model:

IAccountingReport - src/models/UnifiedAccounting.ts

Deprecated Object Structure:

interface IAccountingReport {
  type?: TAccountingReportType; // Enum: TRIAL_BALANCE, BALANCE_SHEET, PROFIT_AND_LOSS  
  ...
}

Replacement: Use individual report objects directly

Balance Sheet:

interface IAccountingBalancesheet {
  id?: string;  
  created_at?: (string | Date | number);  
  updated_at?: (string | Date | number);  
  start_at?: (string | Date | number);  
  end_at?: (string | Date | number);  
  name?: string;  
  currency?: string;  
  net_assets_amount?: number;  
  assets?: IAccountingBalancesheetItem[];  
  liabilities?: IAccountingBalancesheetItem[];  
  equity?: IAccountingBalancesheetItem[];  
  raw?: unknown;
}

Profit and Loss:

interface IAccountingProfitloss {
  id?: string;  
  created_at?: (string | Date | number);  
  updated_at?: (string | Date | number);  
  category_ids?: string[];  
  start_at?: (string | Date | number);  
  end_at?: (string | Date | number);  
  name?: string;  
  currency?: string;  
  income_sections?: IAccountingProfitlossSection[];  
  expenses_sections?: IAccountingProfitlossSection[];  
  cost_of_goods_sold_sections?: IAccountingProfitlossSection[];  
  income_total_amount?: number;  
  net_income_amount?: number;  
  expenses_total_amount?: number;  
  cost_of_goods_sold_total_amount?: number;  
  raw?: unknown;
}

Trial Balance:

interface IAccountingTrialbalance {
  id?: string;  
  created_at?: (string | Date | number);  
  updated_at?: (string | Date | number);  
  start_at?: (string | Date | number);  
  name?: string;  
  currency?: string;  
  end_at?: (string | Date | number);  
  total_debit_amount?: number;  
  total_credit_amount?: number;  
  sub_items?: IAccountingTrialbalanceSubItem[];  
  raw?: unknown;
}

Cash Flow:

interface IAccountingCashflow {
  id?: string;  
  created_at?: (string | Date | number);  
  updated_at?: (string | Date | number);  
  start_at?: (string | Date | number);  
  end_at?: (string | Date | number);  
  category_ids?: string[];  
  contact_id?: string;  name?: string; // e.g. "Cash Flow Statement Q1 2020"  
  currency?: string; // ISO 4217, e.g. "USD"  
  cash_beginning_amount?: number; // Cash at beginning of period  
  cash_ending_amount?: number; // Cash at end of period  
  net_change_in_cash_amount?: number; // Usually ending - beginning  
  operating_sections?: IAccountingCashflowSection[];  
  investing_sections?: IAccountingCashflowSection[];  
  financing_sections?: IAccountingCashflowSection[];  raw?: unknown;
}

interface IAccountingCashflowSection {
  section_name?: string; // e.g. "Operating Activities"  
  total_amount?: number; // Net cash provided/used by this section  
  items?: IAccountingCashflowItem[];
}

interface IAccountingCashflowItem {
  account_id?: string; // If attributable to a specific GL account  
  name?: string; // e.g. "Net Income", "Depreciation", "Equipment"  
  amount?: number; // Positive = inflow, Negative = outflow  
  transaction_ids?: string[]; // Optional linkage to transactions  
  sub_items?: IAccountingCashflowItem[];
}

Migration Recommendation:

Read Operations: Instead of using accounting_report endpoints, use the specific report endpoints
❌ Deprecated: GET /accounting/report?type=BALANCE_SHEET. ✅ Use: GET /accounting/balancesheet
❌ Deprecated: GET /accounting/report?type=PROFIT_AND_LOSS. ✅ Use: GET /accounting/profitloss
❌ Deprecated: GET /accounting/report?type=TRIAL_BALANCE. ✅ Use: GET /accounting/trialbalance
✅ Use: GET /accounting/cashflow (Cash flow was never part of the deprecated report object, but should be accessed directly)
Write Operations: Create individual report objects directly instead of wrapping them in a report object
Field Access: Access report data directly from the individual objects instead of through report.balance_sheet, report.profit_and_loss, etc.

Example:

// Before
const report = await getAccountingReport({
  type: 'BALANCE_SHEET',  
  start_at: '2024-01-01',  
  end_at: '2024-12-31'
});
const assets = report.balance_sheet?.assets;

// After
const balanceSheet = await getAccountingBalancesheet({
  start_at: '2024-01-01',  
  end_at: '2024-12-31'
});
const assets = balanceSheet.assets;

Benefits of Using Individual Objects:

Simpler API: Each report type has its own dedicated endpoint
Better Type Safety: TypeScript can better infer types for specific report objects
Clearer Intent: Code is more explicit about which report type is being accessed
Easier Maintenance: Individual objects are easier to extend and modify independently

Deprecated Types/Interfaces

`IAccountingProfitlossCategory` and `IAccountingProfitlossSubcategory`

Status: Deprecated types - These interfaces are deprecated in favor of IAccountingProfitlossSection

Affected Files:

src/models/UnifiedAccounting.ts
src/models/UnifiedAccounting.joi.ts (marked as @deprecated)
src/models/UnifiedAccounting.proto

Deprecated Types:

interface IAccountingProfitlossCategory {
  name?: string;  amount?: number;  sub_items?: IAccountingProfitlossSubcategory[];}
interface IAccountingProfitlossSubcategory {
  name?: string;  amount?: number;  transaction_ids?: string[];}

Replacement:

interface IAccountingProfitlossSection {
  section_type?: string;  section_name?: string;  total_amount?: number;  accounts?: IAccountingProfitlossAccount[];}
interface IAccountingProfitlossAccount {
  account_id?: string;  account_name?: string;  total_amount?: number;  transaction_ids?: string[];}

Migration Recommendation:

Update TypeScript type definitions to use IAccountingProfitlossSection
Update code that creates or manipulates profit/loss categories to use sections instead
The new structure provides better organization with accounts grouped under sections

Summary by Category

Category	Deprecated Fields Count	Primary Changes
Metadata	2	`key` → `slug`, `type` → `format` (affects 6 models)
Parent/Relationship	4	Various `parent_*_id` → `parent_id`
HRIS	3	`department`, `division`, `location` → `groups`/`locations`
Messaging	4	`channel_id`, `channel_ids`, `parent_message_id`, `root_message_id` → `channels`/`parent_id`
Accounting	8	Multiple field replacements and structural changes
ATS	2	`document_id` → `document_ids`, `departments` → `groups`
Ticketing	1	`category` → `category_id`
Query Parameters	3	Date filter and expand parameter updates
Webhooks	1	`sig` → `sig256`
Deprecated Objects	2	`IAccountingInvoice` with `type='BILL'`, `IAccountingReport`
Deprecated Types	2	`IAccountingProfitlossCategory`, `IAccountingProfitlossSubcategory`

Total Deprecated Fields:

27 unique fields
2 deprecated objects
2 deprecated types across all categories

General Migration Guidelines

1. Backward Compatibility

Deprecated fields will still be supported until JANUARY 7, 2026
Plan to migrate as soon as possible to avoid breaking changes in future API versions

2. Testing

Test all migrations thoroughly in a development environment
Verify that data reads and writes work correctly with the new fields

3. Data Migration

For existing data using deprecated fields, consider:
- Running a one-time migration script to populate new fields from old fields
- Updating your application code to read from both old and new fields during transition
- Gradually migrating writes to use only new fields

4. Documentation

Update your internal documentation and code comments
Notify your team about these changes
Update API integration tests to use new field names

All articles