---
title: "Payroll data model"
url: "https://docs.unified.to/hris/payroll/model"
description: "The Payroll data model object in Unified's Payroll API: 22 fields, including created_at, updated_at and company_id, with types and enum values."
date: "2026-10-20T01:36:58.058Z"
updated: "2026-11-13T20:18:46.414Z"
---
# Payroll data model

Updated: November 13, 2026

 View field support, webhooks, and list parameters for each integration on the [Supported Integrations](https://docs.unified.to/hris/integrations.md) page. 

| Field                          | Type               | Required | Description                                                                                                                                                                                                                                              |
| ------------------------------ | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                             | string             | No       |                                                                                                                                                                                                                                                          |
| created\_at                    | string (date-time) | No       | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                                 |
| updated\_at                    | string (date-time) | No       | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                                 |
| company\_id                    | string             | No       | (reference to HrisCompany)                                                                                                                                                                                                                               |
| group\_id                      | string             | No       | the pay group (hris\_group of type PAY\_GROUP) (reference to HrisGroup)                                                                                                                                                                                  |
| status                         | enum               | No       | Values: DRAFT, PENDING, APPROVED, PROCESSING, PAID, FAILED, CANCELLED                                                                                                                                                                                    |
| type                           | enum               | No       | Values: REGULAR, OFF\_CYCLE, BONUS, CORRECTION, TERMINATION, CONTRACTOR                                                                                                                                                                                  |
| start\_at                      | string (date-time) | No       | pay period start (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                |
| end\_at                        | string (date-time) | No       | pay period end (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                  |
| paid\_at                       | string (date-time) | No       | pay/check date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                  |
| approved\_at                   | string (date-time) | No       | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                                 |
| currency                       | string             | No       |                                                                                                                                                                                                                                                          |
| gross\_amount                  | number             | No       |                                                                                                                                                                                                                                                          |
| net\_amount                    | number             | No       |                                                                                                                                                                                                                                                          |
| employee\_tax\_amount          | number             | No       |                                                                                                                                                                                                                                                          |
| employer\_tax\_amount          | number             | No       |                                                                                                                                                                                                                                                          |
| deduction\_amount              | number             | No       | total employee deductions                                                                                                                                                                                                                                |
| employer\_contribution\_amount | number             | No       | total employer benefit contributions                                                                                                                                                                                                                     |
| total\_cost\_amount            | number             | No       | total company cost/debit for this payroll                                                                                                                                                                                                                |
| user\_ids                      | string\[\]         | No       | employees paid in this payroll                                                                                                                                                                                                                           |
| payslip\_ids                   | string\[\]         | No       |                                                                                                                                                                                                                                                          |
| metadata                       | HrisMetadata\[\]   | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].id                | string             | No       | The ID of the custom field definition (from the metadata/metadata endpoint).                                                                                                                                                                             |
| metadata\[\].value             | object             | No       | The field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES\_NO as true/false; MULTIPLE\_SELECT as an array of option values; otherwise a string. |
| metadata\[\].namespace         | string             | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].format            | enum               | No       | The data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE\_SELECT, MULTIPLE\_SELECT, MEASUREMENT, PRICE, YES\_NO, CURRENCY, URL                                            |
| metadata\[\].extra\_data       | object             | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].slug              | string             | No       | The integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.                                                                       |

## TypeScript

```typescript
export type HrisPayroll = {
	id?: string;
	created_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	updated_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	company_id?: string; // (reference to HrisCompany)
	group_id?: string; // the pay group (hris_group of type PAY_GROUP) (reference to HrisGroup)
	status?: 'DRAFT' | 'PENDING' | 'APPROVED' | 'PROCESSING' | 'PAID' | 'FAILED' | 'CANCELLED';
	type?: 'REGULAR' | 'OFF_CYCLE' | 'BONUS' | 'CORRECTION' | 'TERMINATION' | 'CONTRACTOR';
	start_at?: string-time; // pay period start (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	end_at?: string-time; // pay period end (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	paid_at?: string-time; // pay/check date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	approved_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	currency?: string;
	gross_amount?: number;
	net_amount?: number;
	employee_tax_amount?: number;
	employer_tax_amount?: number;
	deduction_amount?: number; // total employee deductions
	employer_contribution_amount?: number; // total employer benefit contributions
	total_cost_amount?: number; // total company cost/debit for this payroll
	user_ids?: string[]; // employees paid in this payroll
	payslip_ids?: string[];
	metadata?: [];
	raw?: any;
} 
```

## Zod

```typescript
import { z } from 'zod';

export const ZodHrisPayroll = z.object({
	id: z.string().optional(),
	created_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	updated_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	company_id: z.string().optional().describe("(reference to HrisCompany)"),
	group_id: z.string().optional().describe("the pay group (hris_group of type PAY_GROUP) (reference to HrisGroup)"),
	status: z.enum("DRAFT", "PENDING", "APPROVED", "PROCESSING", "PAID", "FAILED", "CANCELLED").optional(),
	type: z.enum("REGULAR", "OFF_CYCLE", "BONUS", "CORRECTION", "TERMINATION", "CONTRACTOR").optional(),
	start_at: z.string-time().optional().describe("pay period start (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	end_at: z.string-time().optional().describe("pay period end (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	paid_at: z.string-time().optional().describe("pay/check date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	approved_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	currency: z.string().optional(),
	gross_amount: z.number().optional(),
	net_amount: z.number().optional(),
	employee_tax_amount: z.number().optional(),
	employer_tax_amount: z.number().optional(),
	deduction_amount: z.number().optional().describe("total employee deductions"),
	employer_contribution_amount: z.number().optional().describe("total employer benefit contributions"),
	total_cost_amount: z.number().optional().describe("total company cost/debit for this payroll"),
	user_ids: z.array().optional().describe("employees paid in this payroll"),
	payslip_ids: z.array().optional(),
	metadata: z.array().optional(),

});
```

## Python

```python
import dataclasses

@dataclasses.dataclass
class HrisPayrollStatus(str, Enum):
	DRAFT = 'DRAFT'
	PENDING = 'PENDING'
	APPROVED = 'APPROVED'
	PROCESSING = 'PROCESSING'
	PAID = 'PAID'
	FAILED = 'FAILED'
	CANCELLED = 'CANCELLED'

@dataclasses.dataclass
class HrisPayrollType(str, Enum):
	REGULAR = 'REGULAR'
	OFF_CYCLE = 'OFF_CYCLE'
	BONUS = 'BONUS'
	CORRECTION = 'CORRECTION'
	TERMINATION = 'TERMINATION'
	CONTRACTOR = 'CONTRACTOR'

@dataclasses.dataclass
class HrisPayroll:
	id: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	created_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	updated_at: Optional[str]
	"""(reference to HrisCompany)"""
	company_id: Optional[str]
	"""the pay group (hris_group of type PAY_GROUP) (reference to HrisGroup)"""
	group_id: Optional[str]
	status: Optional[HrisPayrollStatus]
	type: Optional[HrisPayrollType]
	"""pay period start (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	start_at: Optional[str]
	"""pay period end (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	end_at: Optional[str]
	"""pay/check date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	paid_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	approved_at: Optional[str]
	currency: Optional[str]
	gross_amount: Optional[int]
	net_amount: Optional[int]
	employee_tax_amount: Optional[int]
	employer_tax_amount: Optional[int]
	"""total employee deductions"""
	deduction_amount: Optional[int]
	"""total employer benefit contributions"""
	employer_contribution_amount: Optional[int]
	"""total company cost/debit for this payroll"""
	total_cost_amount: Optional[int]
	"""employees paid in this payroll"""
	user_ids: Optional[List[List[str]]]
	payslip_ids: Optional[List[List[str]]]
	metadata: Optional[PropertyHrisPayrollMetadata]

```
