---
title: "Notice of Deprecation of Fields and Objects (Nov 2025)"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/notice_of_deprecation_of_fields_and_objects_nov_2025-icon.png
date: 2025-11-10T00:00:00.000Z
tag: Guides
description: "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..."
url: "https://docs.unified.to/guides/notice_of_deprecation_of_fields_and_objects_nov_2025"
---

# Notice of Deprecation of Fields and Objects (Nov 2025)
------
_November 10, 2025_

# Deprecated Fields, Objects & List Options


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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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

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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


```typescript
department?: string; // @deprecated
```


**Replacement:**


```typescript
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:**


```typescript
// 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:**


```typescript
division?: string; // @deprecated
```


**Replacement:**


```typescript
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:**


```typescript
// 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:**


```typescript
location?: string; // @deprecated
```


**Replacement:**


```typescript
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:**


```typescript
// 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:**


```typescript
channel_id?: string; // @deprecated
```


**Replacement:**


```typescript
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:**


```typescript
// 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:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


```typescript
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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
expenses_sections?: IAccountingProfitlossSection[];
```


**Migration Recommendation:**


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

**Example:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


```typescript
// 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:**


```typescript
document_id?: string; // @deprecated
```


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


```typescript
primary?: boolean; // @deprecated
```


**Replacement:**


```typescript
is_primary?: boolean;
```


---


## Query Parameters & Filters


### `expand_recurring_events` → `expand`


**Affected Models:**

- `ICalendarEvent`

**Deprecated Parameter:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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:**


```typescript
// 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:**


```typescript
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:**


```typescript
// 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:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:** Use individual report objects directly


**Balance Sheet:**


```typescript
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:**


```typescript
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:**


```typescript
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:**


```typescript
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:**


```typescript
// 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:**


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


**Replacement:**


```typescript
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