---
title: "Create a time off policy"
method: POST
path: "/v1/org/{orgId}/timeoff/policy"
tags: ["timeOffPolicy"]
---

# Create a time off policy

`POST /v1/org/{orgId}/timeoff/policy`

## Path parameters

- `orgId` string, required

## Request body

- CreateTimeOffPolicy
  - `name` string, required — Internal policy name
  - `displayName` string — External policy name displayed to users
  - `description` string — Policy description
  - `guidelines` string — Policy guidelines
  - `type` 'PTO' | 'TOIL' | 'VACATION' | 'SICK' | 'MEDICAL' | 'JURY' | 'OFFSITE' | 'PARENTAL' | 'UNPAID' | 'DISABILITY_SHORT' | 'DISABILITY_LONG' | 'BEREAVEMENT' | 'MILITARY' | 'RELIGIOUS' | 'VOTING' | 'VOLUNTEER' | 'UNKNOWN', required — Type of policy to be created
  - `status` 'ACTIVE' | 'INACTIVE', required — Status of the policy
  - `allocationType` 'UPFRONT' | 'UNLIMITED' | 'ACCRUAL', required — Whether the time off is accrued, received upfront, or is an unlimited policy
  - `annualAllocation` number — Number of days allocated annually
  - `accrualConfig` AccrualConfig
    - `frequency` 'SEMI_MONTHLY' | 'MONTHLY' | 'WEEKLY', required
    - `monthlyDaysOfMonth` integer[]
    - `weeklyStartDate` string, date
    - `weeklyIncrement` integer
    - `balanceCapInWholeDays` integer
    - `accrualOffsetFromStartDate` integer, required
  - `maxConsecutiveDaysPerRequest` number — An optional max number of days allowed per request
  - `minBalance` number — An optional minimum balance
  - `enableCarryOverBalance` boolean — Enable carry over balance.
  - `maxCarryOverBalance` number — An optional maximum carry over balance
  - `carryOverExpirationDate` string — Month and day of carry over expiration.
  - `carryOverExpirationMonths` integer — Months after carry over date that carry over expires.
  - `enablePartialDayRequests` boolean — Allow half day requests
  - `partialDayGranularity` number — Partial day requests can only be made down to this level of granularity (i.e. request % granularity == 0)
  - `enablePartialDayPeriod` boolean — Allow specifying periods of time (e.g. AM, PM) for partial days
  - `disableRequests` boolean — Whether to disable time off requests for this policy
  - `noteRequired` boolean — Whether a note is required for time off requests
  - `filter` string, required — CQL used to determine which jobs the policy applies to
  - `holidayCalendarId` string — an associated holiday calendar, days on this calendar are not deducted from the time off balance
  - `respectPersonCalendar` boolean — when true, a holiday calendar applied to the person via calendar eligibility takes precedence over this policy's holidayCalendarId
  - `disableProratedAllocation` boolean — whether limited allocation policies are prorated based on person start date
  - `prorationRounding` 'UP' | 'NEAREST' | 'HALF' — rounding method for prorating calculations
  - `yearStartDate` string — Month and day of policy year rollover. Defaults to January 1.
  - `policyFromDate` string, date — The date on which this policy's balance/accrual settings come into effect. The policy may have entries before this date, but it will not generate e.g. accrual entries.
  - `policyUntilDate` string, date — The first date after this policy's balance/accrual settings end (i.e. the exclusive end date). The policy may have entries after this date, but it will not generate e.g. accrual entries.
  - `workDays` string[] — Days of the week that count against the time off balance. Defaults to Monday through Friday if not set.
  - `policyEvents` PolicyEvent[]
    - `dateExpr` string, required
    - `action` PolicyAction, required
      - `type` 'OPEN' | 'CLOSE' | 'MOD_ALLOCATION' | 'ADJUST' | 'TRANSFER' | 'PRORATED_MOD' | 'FULL_MOD', required
      - `exprString` string
    - `noteExpr` string
    - `groupId` string
    - `title` string — Display name for the milestone group this event belongs to

## Response `201`

created

- TimeOffPolicy
  - `id` string, required — Globally unique id of time off policy
  - `orgId` string, required — Org that the time off belongs to
  - `name` string, required — Internal policy name
  - `displayName` string — External policy name displayed to users
  - `description` string — Policy description
  - `guidelines` string — Policy guidelines
  - `type` 'PTO' | 'TOIL' | 'VACATION' | 'SICK' | 'MEDICAL' | 'JURY' | 'OFFSITE' | 'PARENTAL' | 'UNPAID' | 'DISABILITY_SHORT' | 'DISABILITY_LONG' | 'BEREAVEMENT' | 'MILITARY' | 'RELIGIOUS' | 'VOTING' | 'VOLUNTEER' | 'UNKNOWN' — Type of policy to be created
  - `status` 'ACTIVE' | 'INACTIVE', required — Status of the policy
  - `allocationType` 'UPFRONT' | 'UNLIMITED' | 'ACCRUAL' — Whether the time off is accrued, received upfront, or is an unlimited policy
  - `annualAllocation` number — Number of days allocated annually
  - `accrualConfig` AccrualConfig
    - `frequency` 'SEMI_MONTHLY' | 'MONTHLY' | 'WEEKLY', required
    - `monthlyDaysOfMonth` integer[]
    - `weeklyStartDate` string, date
    - `weeklyIncrement` integer
    - `balanceCapInWholeDays` integer
    - `accrualOffsetFromStartDate` integer, required
  - `maxConsecutiveDaysPerRequest` number — An optional max number of days allowed per request
  - `minBalance` number — An optional minimum balance
  - `enableCarryOverBalance` boolean — Enable carry over balance.
  - `maxCarryOverBalance` number — An optional maximum carry over balance
  - `carryOverExpirationDate` string — Month and day of carry over expiration.
  - `carryOverExpirationMonths` integer — Months after carry over date that carry over expires.
  - `enablePartialDayRequests` boolean — Allow half day requests
  - `partialDayGranularity` number — Partial day requests can only be made down to this level of granularity (i.e. request % granularity == 0)
  - `enablePartialDayPeriod` boolean — Allow specifying periods of time (e.g. AM, PM) for partial days
  - `disableRequests` boolean — Whether to disable time off requests for this policy
  - `noteRequired` boolean — Whether a note is required for time off requests
  - `filter` string, required — CQL used to determine which jobs the policy applies to
  - `holidayCalendarId` string — an associated holiday calendar, days on this calendar are not deducted from the time off balance
  - `respectPersonCalendar` boolean — when true, a holiday calendar applied to the person via calendar eligibility takes precedence over this policy's holidayCalendarId
  - `disableProratedAllocation` boolean — whether limited allocation policies are prorated based on person start date
  - `prorationRounding` 'UP' | 'NEAREST' | 'HALF' — rounding method for prorating calculations
  - `yearStartDate` string — Month and day of policy year rollover. Defaults to January 1.
  - `policyFromDate` string, date — The date on which this policy's balance/accrual settings come into effect. The policy may have entries before this date, but it will not generate e.g. accrual entries.
  - `policyUntilDate` string, date — The first date after this policy's balance/accrual settings end (i.e. the exclusive end date). The policy may have entries after this date, but it will not generate e.g. accrual entries.
  - `workDays` string[] — Days of the week that count against the time off balance. Defaults to Monday through Friday if not set.
  - `policyEvents` PolicyEvent[]
    - `dateExpr` string, required
    - `action` PolicyAction, required
      - `type` 'OPEN' | 'CLOSE' | 'MOD_ALLOCATION' | 'ADJUST' | 'TRANSFER' | 'PRORATED_MOD' | 'FULL_MOD', required
      - `exprString` string
    - `noteExpr` string
    - `groupId` string
    - `title` string — Display name for the milestone group this event belongs to
  - `createId` string — created by user id
  - `createBehalfId` string — created on behalf of user id
  - `createAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `createAt` string — created timestamp
  - `updateAt` string — updated timestamp
  - `updateId` string — updated by user id
  - `updateBehalfId` string — last updated on behalf of user id
  - `updateAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `deleteId` string — deleted by user id
  - `deleteBehalfId` string — deleted on behalf of user id
  - `deleteAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `deleteAt` string — deleted timestamp

## Other responses

- `400` — bad request
- `401` — not authorized
- `404` — not found
- `500` — Not Implemented

---

[API](https://skmtc.net/charthop/apis/charthop-api.md) · [All operations](https://skmtc.net/charthop/apis/charthop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/charthop/charthop-api/revisions/2de21f45f447/schema)