Notice of Deprecation of Fields and Objects (Nov 2025)

Updated:


November 10, 2025

Deprecated Fields, Objects & List Options

Updated:

At Unified, we have always built our unified data-models with a lot of thoughtful attention to detail, so that they never have to be 'versioned' due to backward-compatibility issues.

In fact, when we launch a new data object or a brand new category, designing our unified data models always takes longer than actually 'coding' the integrations. Our customers have noticed and have told us that we have the best designed unified data models in the business.

Over the 2.5 years, as we've made improvements to the unified data-models, we have kept older fields and objects around so that our customers do not have to change their applications.

Today, we are announcing some deprecations of fields, data-models and list options that have been improved with others and will shortly be removed in our system.

This document provides a comprehensive breakdown of all deprecation 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


Table of Contents

  1. MetadataMetadata Fields
  2. Parent Fields
  3. HRIS Employee Fields
  4. MessagingMessage Fields
  5. Accounting Fields
  6. ATS (Applicant Tracking System) Fields
  7. Ticketing Fields
  8. Calendar Fields
  9. Query Parameters & Filters
  10. Webhook Fields
  11. Deprecated Objects/Usage Patterns
  12. Deprecated Types/Interfaces

MetadataMetadata Fields

Field: key → slug

  • the reason was the key was a confusing name and could denote something else that it wasn't

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

  • the reason was the type was a confusing name and could denote something else that it wasn't

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

  • the reason was that we standardized across all of our unified data models the field name of parent_id when it denoted a parent of the current object (and is the same object)

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

  • we unified all HR 'grouping' objects into one called HRIS Group. Groups have types that denote if they are a department, business unit, team, …

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

  • the reason was so we could include additional channel information, such as the channel name , as well as its id

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'
}

Calendar Fields

Field:primary → is_primary

Affected Model:

  • ICalendarCalendar - src/models/UnifiedCalendar.ts

Deprecated Field:

primary?: boolean; // @deprecated

Replacement:

is_primary?: boolean;

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

CategoryDeprecated Fields CountPrimary Changes
Metadata2key → slug, type → format (affects 6 models)
Parent/Relationship4Various parent_*_id → parent_id
HRIS3department, division, location → groups/locations
Messaging4channel_id, channel_ids, parent_message_id, root_message_id → channels/parent_id
Accounting8Multiple field replacements and structural changes
ATS2document_id → document_ids, departments → groups
Ticketing1category → category_id
Query Parameters3Date filter and expand parameter updates
Webhooks1sig → sig256
Deprecated Objects2IAccountingInvoice with type='BILL', IAccountingReport
Deprecated Types2IAccountingProfitlossCategory, 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
Share
All guidesFieldsAccounting Account Type Hierarchy in UnifiedAdvertising Report Metrics by IntegrationAmazon S3: Required IAM PermissionsATS to Vector DB: How to Power Talent Intelligence with Real-Time DataBuilding AI applications with Unified and LangbaseConcur & Concur (Company) — Connection GuideConfigure Greenhouse Native Candidate WebhooksConfigure Salesforce Meetings and Notes for UnifiedConnect Amazon Seller Central to Unified.toConnecting BambooHR via OAuth 2Connecting Google Workspace Integrations with a Service AccountCorrect WelcomeKit Scopes for Jungle IntegrationCreating Ads using the Unified Ads APICreating Walmart Items via UnifiedEnd-Users, Integrations, and ConnectionsEnriching Unified Objects with Custom MetadataEnterprise-managed authorization (EMA) with a static keyEnterprise-managed authorization (EMA) with a workspace secretEnterprise-managed authorization (EMA) with Microsoft Entra IDExtended observability — pushing API logs to ClickHouseExtended observability — pushing API logs to Grafana / LokiExtended Observability - Pushing API Logs to your Datadog InstanceFacebook Messenger Webhook SetupFireflies Integration GuideGetting started with WorkableHandling Delegated vs. Application Scopes in Microsoft IntegrationsHiBob & Unified: connection and time off guideHow long are logs retainedHow to access employees and usersHow to add API support for the Create Activity in CrelateHow to Associate a Connection ID with Your End-UserHow to build a Candidate Assessment product withHow to build a candidate sourcing or job board app with Unified.toHow to build a Discord support bot with Unified.to and LangbaseHow to Build a Fintech Application with Unified's Payments APIHow to Build an E-Commerce Product Integration with UnifiedHow to build an invoicing system with Unified.toHow to build Enterprise Search using RAGHow to configure Bullhorn Redirect URI for creating a connectionHow to configure webhooks in HubSpotHow to configure webhooks in Thrive LearningHow to configure webhooks in Toast for UnifiedHow to Connect Anthropic to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Cohere to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Google Gemini to Real-Time SaaS Data with Unified.to MCP ServerHow to connect HiBob (Bob) to Unified with OAuth 2.0How to Connect LLMs to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect OpenAI to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Zoom and Zoom PhoneHow to create a Connection In Microsoft TeamsHow to create a token-based connection in HighlevelHow to Create a Unified.to Connection to HighLevelHow to Create a Xero Connection in Unified.toHow to create and configure webhooksHow to create Connection with HubspotHow to customize portal URLs for Stripe and GoCardlessHow to filter webhook eventsHow-to Get a Private Support Channel for Your Unified IntegrationHow to get help fromHow to get your 8x8 Connect API Key, Account ID and SMS Subaccount ID (optional): Step-by-step guideHow to get your ADP Workforce Now Oauth2 client ID, Oauth2 client secret, Oauth2 PEM certificate and Oauth2 private key: Step-by-step guideHow to get your Amazon S3 AWS Region, AWS S3 Key, AWS S3 Secret and AWS S3 Bucket(s) (optional, comma-separated): Step-by-step guideHow to get your Ashby API Key: Step-by-step guideHow to get your Brex API token: Step-by-step guideHow to get your Bullhorn OAuth2 Client ID, OAuth2 Client Secret, API Username and API Password: Step-by-step guideHow to get your Ceridian Dayforce Username, Password and Client Namespace: Step-by-step guideHow to get your Crelate API key: Step-by-step guideHow to get your Dashlane API Key: Step-by-step guideHow to get your Deel Access Token: Step-by-step guideHow to get your Dialpad API Key: Step-by-step guideHow to get your Discord OAuth 2 credentials and bot tokenHow to get your ELMO client ID and client secret: Step-by-step guideHow to get your Gainsight Client ID, Client Secret and Gainsight API Domain: Step-by-step guideHow to get your Greenhouse API Key and Job board token: Step-by-step guideHow to get your Helpscout API Key: Step-by-step guideHow to get your HiBob Service User ID and Service User Token: Step-by-step guideHow to get your HighLevel API Key and Location ID: Step-by-step guideHow to get your HubSpot developer key and OAuth 2 credentials (Legacy Apps)How to get your Humaans API Key: Step-by-step guideHow to get your iCIMS API Username, API Password and Customer ID: Step-by-step guideHow to get your JobDiva Client ID, Username/email and Password: Step-by-step guideHow to get your Jobvite API Key, API Key Secret and Email: Step-by-step guideHow to get your Lever API Key: Step-by-step guideHow to get your Loxo Agency slug, API Key and Agency ID: Step-by-step guideHow to get your Microsoft Active Directory / Entra ID Client ID, Client Secret and Tenant ID: Step-by-step guideHow to get your Microsoft Azure AD OAuth 2 credentialsHow to get your OAuth 2 credentials for GmailHow to get your OAuth 2 credentials for Microsoft Dynamics 365How to get your OAuth 2 credentials in PipeDriveHow to get your OpenAI API Key: Step-by-step guideHow to get your Paycom SID/Username and Token/Password: Step-by-step guideHow to get your PCRecruiter Username, Password, Database ID, App Key and App ID: Step-by-step guideHow to get your SAP SuccessFactors (OpenID Connect) Username, Password, Client ID, Client Secret, Dependency Name, IAS Host and API URL: Step-by-step guideHow to get your SAP SuccessFactors Username, Company ID, Password and API URL: Step-by-step guideHow to get your Shopify Admin API access token and Store ID: Step-by-step guideHow to get your Wayfair Client ID, Client Secret and Vendor Encrypted Key: Step-by-step guideHow to get your Workable API Token and Subdomain: Step-by-step guideHow to get your yotpo APP Key / Store ID and Secret Key: Step-by-step guideHow to Handle Attachments in Invoice, Bill and Credit MemoHow to Manage Google Ad Manager Orders, Line Items and Creatives with theHow to migrate or import your integrations into Unified.toHow to obtain your GitHub OAuth2 credentialsHow to Power Claude with Live Customer Data Using Unified MCPHow to receive assessment orders from an ATS with Unified.toHow to register a Google developer app and get OAuth 2 credentialsHow to Register a HiBob Developer App and Get OAUTH2 CredentialsHow to register a Salesforce developer app and get OAuth 2 credentialsHow to register a Slack developer account and get OAuth 2 credentialsHow to Register a Workday Developer App and Get OAUTH2 CredentialsHow to Register a Workday Developer App and Get OAUTH2/ SOAP CredentialsHow to Register a ZendeskSell Developer App and Get OAUTH2 CredentialsHow to Register a Zoho Developer App and Get OAUTH2 CredentialsHow to Register an ADP Developer App and Get OAUTH2 CredentialsHow to Register an Atlassian Developer App and Get OAUTH2 CredentialsHow to Register your Facebook OAuth2 ApplicationHow to Register your Google Ads OAuth2 ApplicationHow to Register your MetaAds OAuth2 applicationHow To Request & Write Raw Integration DataHow to Retrieve Microsoft Dynamics 365 Business Central CredentialsHow to set up a custom API URL with a CNAMEHow to Set Up a Google Meet Meeting Bot with UnifiedHow to set up a HiBob marketplace installHow to Set Up a Microsoft Teams Bot with UnifiedHow to Set Up a Microsoft Teams Meeting Bot with UnifiedHow to Set Up a Webex Meeting Bot with UnifiedHow to Set Up a Zoom Meeting Bot with UnifiedHow to set up and configure NotionHow to set up Google Business Profile API access and get OAuth 2 credentialsHow to Set Up LinkedIn Webhooks with UnifiedHow to set up native webhooks for QuickBooks Online with UnifiedHow to set up Slack webhooks using event subscriptionsHow to set up Telegram (bot) with Unified.toHow to set up your scopes in HubSpotHow to setup a Freshbooks developer appHow to setup a TikTok Shop applicationHow to Setup AWS Assume Role for AWS Secret ManagerHow to setup Oracle JD EdwardsHow to Setup Quickbooks DesktopHow to setup Sage 100 with Unified.toHow to test webhooks in the Synthetic Data (Sandbox) environmentHow to troubleshoot unhealthy connectionsHow to troubleshoot unhealthy webhooksHow to Use Decision Models with the Unified GenAI APIHow to use SCIM with the Unified APIHow to use the Passthrough APIHow to Use Unified.to's Generative AI API with OpenAI and ClaudeHow to use User Provisioning and Verification with UnifiedHow virtual webhook retry and recovery worksIntegration set-up guide for LeverManaging custom validation rules in SalesforceNetSuite Authentication Setup for UnifiedOracle HCM / Taleo OAuth Credentials GuideRetrieval-Augmented Generation (RAG)SalesForce (External Client Apps) on Multiple OrganizationsSAML Single-Sign-OnScaling MCP Tools with Anthropic's (& OpenAI's) Defer LoadingScaling MCP Tools with Anthropic's Programmatic Tool CallingSet Environments for your Unified.to WorkspaceSetting up a Slack Bot Connection with Unified.toSetting up OAuth 2 Credentials for Greenhouse's APIsTrello Connection Guide in UnifiedUnderstanding OAuth2 Authorization flowsUnderstanding Response Time Headers in the Unified APIUnified Assessment API: Embed Assessments Inside ATS PlatformsUnified's MCP ServerUnified MCP Server with LangChain and LangGraphUnlock real-time data with virtual webhooksUse Unified to sign in your users into your applicationVincere OAuth Setup Guide for UnifiedWhy you can't use Unified's OAuth2 credentials to authorize your end users on ProductionWorkable: Creating candidates and attaching them to jobsWorkday vs Workday Legacy — Why Unified.to Supports BothWorking with hierarchical tree data in Storage, Messaging, and KMS APIs
Are we missing anything? Let us know
Was this page helpful?