--- title: "Create a time off policy" method: POST path: "/time-off/policies" --- # Create a time off policy `POST /time-off/policies` ## Request - Base URL: `https://sandbox.checkhq.com` - URL: `https://sandbox.checkhq.com/time-off/policies` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a time off policy for a company. Set the configuration object that matches `accrual_method`: `annual_grant`, `per_payroll`, or `per_hour_worked`. ## Request body - object - `company` string, required: ID of the company the policy belongs to. - `name` string, required: Name of the policy. - `active` boolean: Whether the policy can be assigned to employees. Defaults to `true`. - `policy_year` object: The annual cycle of the policy, which controls when annual grants are made, when `max_accrual_per_policy_year` resets, and when unused hours roll over or expire. Defaults to a `fixed_date` policy year starting January 1st. - `basis` 'fixed_date' | 'assignment': `fixed_date` resets the policy year on the same calendar date for every employee. `assignment` resets it on the anniversary of each assignment's `effective_start`. - `date` string, nullable: The date the policy year resets, in `MM-DD` format. Only used when `basis` is `fixed_date`. Defaults to `01-01`. - `earning_type` 'pto' | 'sick', required: The type of time off the policy manages. - `earning_code` string, nullable: ID of an earning code whose type matches `earning_type`. Use this to offer more than one policy of the same earning type. - `accrual_method` 'annual_grant' | 'per_payroll' | 'per_hour_worked' | 'none', required: How hours are accrued on the policy. - `annual_grant` object, nullable: Settings for policies with `accrual_method` of `annual_grant`. - `hours` string, decimal: Hours granted on the first day of each policy year. - `partial_year_method` 'prorate' | 'full': How hours are granted when an assignment starts partway through a policy year. `prorate` grants a prorated share of `hours` for the rest of the year; `full` grants the full `hours`. - `per_payroll` object, nullable: Settings for policies with `accrual_method` of `per_payroll`. Hours are spread evenly across an employee's regular payrolls based on the payroll's pay frequency. Off-cycle payrolls don't accrue hours. - `hours_per_year` string, decimal: Hours accrued over a full year of regular payrolls. - `per_hour_worked` object, nullable: Settings for policies with `accrual_method` of `per_hour_worked`. The employee accrues `hours` for every `per_hours_worked` hours they work on a payroll. - `hours` string, decimal: Hours accrued for every `per_hours_worked` hours worked. - `per_hours_worked` string, decimal: Hours worked needed to accrue `hours`. - `include_overtime` boolean: Whether overtime hours count as hours worked. Defaults to `true`. - `limits` object: Caps on the employee's balance and accrual. A `null` limit isn't enforced. - `max_balance` string, decimal, nullable: The maximum balance an employee can hold. When the balance reaches this cap, accrual pauses until the balance drops below it. - `min_balance` string, decimal, nullable: The lowest balance an employee can reach by spending hours. A negative value lets employees borrow against future accrual. `null` allows an unlimited negative balance. - `max_rollover` string, decimal, nullable: The maximum number of unused hours that carry over into the next policy year. Hours above this cap expire when the policy year ends. `null` allows unlimited rollover. - `max_accrual_per_policy_year` string, decimal, nullable: The maximum number of hours an employee can accrue in one policy year. - `accrual_waiting_period_days` integer: The number of days after the assignment's `effective_start` before the employee starts accruing hours. - `usage_waiting_period_days` integer: The number of days after the assignment's `effective_start` before the employee can spend hours. - `metadata` object: Additional loosely structured information to associate with the object. ## Response `200` 200 - TimeOffPolicy - `id` string: Unique identifier for the policy. - `company` string: ID of the company the policy belongs to. - `name` string: Name of the policy. - `active` boolean: Whether the policy can be assigned to employees. Defaults to `true`. - `policy_year` object: The annual cycle of the policy, which controls when annual grants are made, when `max_accrual_per_policy_year` resets, and when unused hours roll over or expire. Defaults to a `fixed_date` policy year starting January 1st. - `basis` 'fixed_date' | 'assignment': `fixed_date` resets the policy year on the same calendar date for every employee. `assignment` resets it on the anniversary of each assignment's `effective_start`. - `date` string, nullable: The date the policy year resets, in `MM-DD` format. Only used when `basis` is `fixed_date`. Defaults to `01-01`. - `earning_type` 'pto' | 'sick': The type of time off the policy manages. - `earning_code` string, nullable: ID of an earning code whose type matches `earning_type`. Use this to offer more than one policy of the same earning type. - `accrual_method` 'annual_grant' | 'per_payroll' | 'per_hour_worked' | 'none': How hours are accrued on the policy. - `annual_grant` object, nullable: Settings for policies with `accrual_method` of `annual_grant`. - `hours` string, decimal: Hours granted on the first day of each policy year. - `partial_year_method` 'prorate' | 'full': How hours are granted when an assignment starts partway through a policy year. `prorate` grants a prorated share of `hours` for the rest of the year; `full` grants the full `hours`. - `per_payroll` object, nullable: Settings for policies with `accrual_method` of `per_payroll`. Hours are spread evenly across an employee's regular payrolls based on the payroll's pay frequency. Off-cycle payrolls don't accrue hours. - `hours_per_year` string, decimal: Hours accrued over a full year of regular payrolls. - `per_hour_worked` object, nullable: Settings for policies with `accrual_method` of `per_hour_worked`. The employee accrues `hours` for every `per_hours_worked` hours they work on a payroll. - `hours` string, decimal: Hours accrued for every `per_hours_worked` hours worked. - `per_hours_worked` string, decimal: Hours worked needed to accrue `hours`. - `include_overtime` boolean: Whether overtime hours count as hours worked. Defaults to `true`. - `limits` object: Caps on the employee's balance and accrual. A `null` limit isn't enforced. - `max_balance` string, decimal, nullable: The maximum balance an employee can hold. When the balance reaches this cap, accrual pauses until the balance drops below it. - `min_balance` string, decimal, nullable: The lowest balance an employee can reach by spending hours. A negative value lets employees borrow against future accrual. `null` allows an unlimited negative balance. - `max_rollover` string, decimal, nullable: The maximum number of unused hours that carry over into the next policy year. Hours above this cap expire when the policy year ends. `null` allows unlimited rollover. - `max_accrual_per_policy_year` string, decimal, nullable: The maximum number of hours an employee can accrue in one policy year. - `accrual_waiting_period_days` integer: The number of days after the assignment's `effective_start` before the employee starts accruing hours. - `usage_waiting_period_days` integer: The number of days after the assignment's `effective_start` before the employee can spend hours. - `metadata` object: Additional loosely structured information to associate with the object. ## Other responses - `400`: 400 ## Changes - **2026-11-03** `5a54f5eb888b`: 1 info - endpoint added [Operation history](https://skmtc.dev/checkhq/apis/check-api/changes/time-off/policies/post.md) --- [API](https://skmtc.dev/checkhq/apis/check-api.md) - [All operations](https://skmtc.dev/checkhq/apis/check-api/llms.txt) - [OpenAPI document](https://skmtc.dev/checkhq/apis/check-api/revisions/5a54f5eb888b?raw)