Time Off Policies

Manage time off policies

Endpoints

GET/v2/organizations/{organization_id}/time_off_policies
POST/v2/organizations/{organization_id}/time_off_policies
GET/v2/organizations/{organization_id}/time_off_policies/user_policies
GET/v2/time_off_policies/{time_off_policy_id}
PUT/v2/time_off_policies/{time_off_policy_id}
DELETE/v2/time_off_policies/{time_off_policy_id}
POST/v2/time_off_policies/{time_off_policy_id}/archive
POST/v2/time_off_policies/{time_off_policy_id}/restore

List organization time off policies

GET/v2/organizations/{organization_id}/time_off_policies

Returns a collection of time off policies for the given organization.

Parameters

Name	In	Type	Description
organization_idrequired	path	integer (int32)
page_start_id	query	integer (int32)	The page start ID.
page_limit	query	integer (int32)	The default page size
status	query	string	Policy status Possible values`activearchivedall`

Responses

200A list of time off policies

object

time_off_policiesarray
array<object>
items
object
TimeOffPolicy model
- idinteger required
  Time off policy ID
- organization_idinteger required
  Organization ID
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- namestring required
  Time off policy name
- created_by_idinteger
  User ID who created the policy
- auto_add_new_usersboolean required
  Automatically add new members to this policy
- allow_negative_balancesboolean required
  Member can request time off before having the balance for it.
- requires_approvalboolean required
  When false time off requests are automatically approved.
- balance_rolls_over_annuallyboolean required
  balance rolls over annually
- paidboolean required
  When true members will be paid for time off taken.
- statusstring required
  Policy status
- policy_typestring required
  Type of policy
- policy_configobject required
  object
  starting_balancenumber
  Starting balance (hours)
  hours_perinteger
  Hours per at amount accrued
  hours_workedinteger
  Hours worked at amount accrued
  maximum_to_accrueinteger
  Maximum amount of time off that can be accrued per year. (hours)
  hours_per_yearinteger
  Hours per year
  hours_per_monthnumber
  Hours per month
  accrual_periodstring
  Accrual period. If set to "month", hours_per_month is required. If set to "year", hours_per_year is required
  accrual_daystring
  Day of the month when accrual happens
  prorate_on_startboolean
  Whether to prorate time based on start date
- membership_rulesobject
  object
  countriesArray[String] required
  ISO 3166-1 alpha-2 country codes
  employment_typesArray[String] required
  Employment type filters

Example response

json

{
  "time_off_policies": [
    {
      "id": 0,
      "organization_id": 0,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "name": "string",
      "created_by_id": 0,
      "auto_add_new_users": false,
      "allow_negative_balances": false,
      "requires_approval": false,
      "balance_rolls_over_annually": false,
      "paid": false,
      "status": "string",
      "policy_type": "string",
      "policy_config": {
        "starting_balance": 0,
        "hours_per": 0,
        "hours_worked": 0,
        "maximum_to_accrue": 0,
        "hours_per_year": 0,
        "hours_per_month": 0,
        "accrual_period": "month",
        "accrual_day": "first_day_of_month",
        "prorate_on_start": false
      },
      "membership_rules": {
        "countries": null,
        "employment_types": null
      }
    }
  ]
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Create time off policy

POST/v2/organizations/{organization_id}/time_off_policies

Creates a new time off policy for the given organization.

accrual_policy fields by accrual_type:

maximum_to_accrue is required for hours_worked, annual, and joined_date.

none — starting_balance (optional)
hours_worked — hours_per (required), hours_worked (required), maximum_to_accrue (required)
annual — hours_per_year (required), maximum_to_accrue (required)
joined_date — hours_per_year (required), maximum_to_accrue (required)
monthly — accrual_period (required: month or year), accrual_day (required: first_day_of_month, monthly_anniversary, or last_day_of_month), prorate_on_start (optional); plus hours_per_month (required when accrual_period=month) or hours_per_year (required when accrual_period=year)

When membership_rules are provided, they take precedence over time_off_policy_user_ids. Additionally, auto_add_new_users defaults to true when membership_rules are provided.

Returns the created time off policy.

Parameters

Name	In	Type	Description
organization_idrequired	path	integer (int32)

Request body

object

Create time off policy

namestring required
Policy name
accrual_typestring required
accrual_policyobject
Accrual configuration (depends on accrual_type)
object
Accrual configuration (depends on accrual_type)
- hours_per_yearnumber
- hours_workednumber
- hours_pernumber
- maximum_to_accruenumber
  Max accrual hours/year (required except none and monthly)
- hours_per_monthnumber
- accrual_periodstring
- accrual_daystring
- prorate_on_startboolean
- starting_balancenumber
allow_negative_balancesboolean required
requires_approvalboolean required
balance_rolls_over_annuallyboolean required
paidboolean required
auto_add_new_usersboolean
time_off_policy_user_idsarray
User IDs to add as members
array<integer>
User IDs to add as members
items
integer(int32)
membership_rulesobject
Auto-membership rules
object
Auto-membership rules
- countriesarray
  ISO 3166-1 alpha-2 country codes
  array<string>
  ISO 3166-1 alpha-2 country codes
  items
  string
- employment_typesarray
  Member employment type filter
  array<string>
  Member employment type filter
  items
  string

Responses

201A time off policy

object

time_off_policyobject
object
TimeOffPolicy model
- idinteger required
  Time off policy ID
- organization_idinteger required
  Organization ID
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- namestring required
  Time off policy name
- created_by_idinteger
  User ID who created the policy
- auto_add_new_usersboolean required
  Automatically add new members to this policy
- allow_negative_balancesboolean required
  Member can request time off before having the balance for it.
- requires_approvalboolean required
  When false time off requests are automatically approved.
- balance_rolls_over_annuallyboolean required
  balance rolls over annually
- paidboolean required
  When true members will be paid for time off taken.
- statusstring required
  Policy status
- policy_typestring required
  Type of policy
- policy_configobject required
  object
  - starting_balancenumber
    Starting balance (hours)
  - hours_perinteger
    Hours per at amount accrued
  - hours_workedinteger
    Hours worked at amount accrued
  - maximum_to_accrueinteger
    Maximum amount of time off that can be accrued per year. (hours)
  - hours_per_yearinteger
    Hours per year
  - hours_per_monthnumber
    Hours per month
  - accrual_periodstring
    Accrual period. If set to "month", hours_per_month is required. If set to "year", hours_per_year is required
  - accrual_daystring
    Day of the month when accrual happens
  - prorate_on_startboolean
    Whether to prorate time based on start date
- membership_rulesobject
  object
  - countriesArray[String] required
    ISO 3166-1 alpha-2 country codes
  - employment_typesArray[String] required
    Employment type filters

Example response

json

{
  "time_off_policy": {
    "id": 0,
    "organization_id": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "name": "string",
    "created_by_id": 0,
    "auto_add_new_users": false,
    "allow_negative_balances": false,
    "requires_approval": false,
    "balance_rolls_over_annually": false,
    "paid": false,
    "status": "string",
    "policy_type": "string",
    "policy_config": {
      "starting_balance": 0,
      "hours_per": 0,
      "hours_worked": 0,
      "maximum_to_accrue": 0,
      "hours_per_year": 0,
      "hours_per_month": 0,
      "accrual_period": "month",
      "accrual_day": "first_day_of_month",
      "prorate_on_start": false
    },
    "membership_rules": {
      "countries": null,
      "employment_types": null
    }
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

List organization time off policies per user

GET/v2/organizations/{organization_id}/time_off_policies/user_policies

Returns active time off policies that the specified user is a member of.

Used to determine which policies are available when creating a time off request.

Parameters

Name	In	Type	Description
organization_idrequired	path	integer (int32)
user_idrequired	query	integer (int32)	User ID to list policies for
page_start_id	query	integer (int32)	The page start ID.
page_limit	query	integer (int32)	The default page size

Responses

200A list of time off policies

object

time_off_policiesarray
array<object>
items
object
TimeOffPolicy model
- idinteger required
  Time off policy ID
- organization_idinteger required
  Organization ID
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- namestring required
  Time off policy name
- created_by_idinteger
  User ID who created the policy
- auto_add_new_usersboolean required
  Automatically add new members to this policy
- allow_negative_balancesboolean required
  Member can request time off before having the balance for it.
- requires_approvalboolean required
  When false time off requests are automatically approved.
- balance_rolls_over_annuallyboolean required
  balance rolls over annually
- paidboolean required
  When true members will be paid for time off taken.
- statusstring required
  Policy status
- policy_typestring required
  Type of policy
- policy_configobject required
  object
  starting_balancenumber
  Starting balance (hours)
  hours_perinteger
  Hours per at amount accrued
  hours_workedinteger
  Hours worked at amount accrued
  maximum_to_accrueinteger
  Maximum amount of time off that can be accrued per year. (hours)
  hours_per_yearinteger
  Hours per year
  hours_per_monthnumber
  Hours per month
  accrual_periodstring
  Accrual period. If set to "month", hours_per_month is required. If set to "year", hours_per_year is required
  accrual_daystring
  Day of the month when accrual happens
  prorate_on_startboolean
  Whether to prorate time based on start date
- membership_rulesobject
  object
  countriesArray[String] required
  ISO 3166-1 alpha-2 country codes
  employment_typesArray[String] required
  Employment type filters

Example response

json

{
  "time_off_policies": [
    {
      "id": 0,
      "organization_id": 0,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "name": "string",
      "created_by_id": 0,
      "auto_add_new_users": false,
      "allow_negative_balances": false,
      "requires_approval": false,
      "balance_rolls_over_annually": false,
      "paid": false,
      "status": "string",
      "policy_type": "string",
      "policy_config": {
        "starting_balance": 0,
        "hours_per": 0,
        "hours_worked": 0,
        "maximum_to_accrue": 0,
        "hours_per_year": 0,
        "hours_per_month": 0,
        "accrual_period": "month",
        "accrual_day": "first_day_of_month",
        "prorate_on_start": false
      },
      "membership_rules": {
        "countries": null,
        "employment_types": null
      }
    }
  ]
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Get time off policy

GET/v2/time_off_policies/{time_off_policy_id}

Returns the time off policy with the given ID.

Parameters

Name	In	Type	Description
time_off_policy_idrequired	path	integer (int32)	Time off policy ID

Responses

200A time off policy

object

time_off_policyobject
object
TimeOffPolicy model
- idinteger required
  Time off policy ID
- organization_idinteger required
  Organization ID
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- namestring required
  Time off policy name
- created_by_idinteger
  User ID who created the policy
- auto_add_new_usersboolean required
  Automatically add new members to this policy
- allow_negative_balancesboolean required
  Member can request time off before having the balance for it.
- requires_approvalboolean required
  When false time off requests are automatically approved.
- balance_rolls_over_annuallyboolean required
  balance rolls over annually
- paidboolean required
  When true members will be paid for time off taken.
- statusstring required
  Policy status
- policy_typestring required
  Type of policy
- policy_configobject required
  object
  - starting_balancenumber
    Starting balance (hours)
  - hours_perinteger
    Hours per at amount accrued
  - hours_workedinteger
    Hours worked at amount accrued
  - maximum_to_accrueinteger
    Maximum amount of time off that can be accrued per year. (hours)
  - hours_per_yearinteger
    Hours per year
  - hours_per_monthnumber
    Hours per month
  - accrual_periodstring
    Accrual period. If set to "month", hours_per_month is required. If set to "year", hours_per_year is required
  - accrual_daystring
    Day of the month when accrual happens
  - prorate_on_startboolean
    Whether to prorate time based on start date
- membership_rulesobject
  object
  - countriesArray[String] required
    ISO 3166-1 alpha-2 country codes
  - employment_typesArray[String] required
    Employment type filters

Example response

json

{
  "time_off_policy": {
    "id": 0,
    "organization_id": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "name": "string",
    "created_by_id": 0,
    "auto_add_new_users": false,
    "allow_negative_balances": false,
    "requires_approval": false,
    "balance_rolls_over_annually": false,
    "paid": false,
    "status": "string",
    "policy_type": "string",
    "policy_config": {
      "starting_balance": 0,
      "hours_per": 0,
      "hours_worked": 0,
      "maximum_to_accrue": 0,
      "hours_per_year": 0,
      "hours_per_month": 0,
      "accrual_period": "month",
      "accrual_day": "first_day_of_month",
      "prorate_on_start": false
    },
    "membership_rules": {
      "countries": null,
      "employment_types": null
    }
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Update time off policy

PUT/v2/time_off_policies/{time_off_policy_id}

Updates a time off policy. Only pass in the fields you want to change.

Updatable fields: name, accrual_policy, allow_negative_balances, requires_approval, balance_rolls_over_annually, paid, auto_add_new_users, and time_off_policy_user_ids (list-based policies only).

Immutable after creation: accrual_type and membership_rules. Use accrual_policy to update the configuration within the existing accrual type. For rules-based policies, member assignment cannot be modified via the API.

Returns the updated time off policy.

Parameters

Name	In	Type	Description
time_off_policy_idrequired	path	integer (int32)	Time off policy ID

Request body

object

Update time off policy

namestring
Policy name
accrual_policyobject
Accrual configuration (depends on accrual_type)
object
Accrual configuration (depends on accrual_type)
- hours_per_yearnumber
- hours_workednumber
- hours_pernumber
- maximum_to_accruenumber
  Max accrual hours/year (required except none and monthly)
- hours_per_monthnumber
- accrual_periodstring
- accrual_daystring
- prorate_on_startboolean
- starting_balancenumber
allow_negative_balancesboolean
requires_approvalboolean
balance_rolls_over_annuallyboolean
paidboolean
auto_add_new_usersboolean
time_off_policy_user_idsarray
User IDs to set as members
array<integer>
User IDs to set as members
items
integer(int32)

Responses

200A time off policy

object

time_off_policyobject
object
TimeOffPolicy model
- idinteger required
  Time off policy ID
- organization_idinteger required
  Organization ID
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- namestring required
  Time off policy name
- created_by_idinteger
  User ID who created the policy
- auto_add_new_usersboolean required
  Automatically add new members to this policy
- allow_negative_balancesboolean required
  Member can request time off before having the balance for it.
- requires_approvalboolean required
  When false time off requests are automatically approved.
- balance_rolls_over_annuallyboolean required
  balance rolls over annually
- paidboolean required
  When true members will be paid for time off taken.
- statusstring required
  Policy status
- policy_typestring required
  Type of policy
- policy_configobject required
  object
  - starting_balancenumber
    Starting balance (hours)
  - hours_perinteger
    Hours per at amount accrued
  - hours_workedinteger
    Hours worked at amount accrued
  - maximum_to_accrueinteger
    Maximum amount of time off that can be accrued per year. (hours)
  - hours_per_yearinteger
    Hours per year
  - hours_per_monthnumber
    Hours per month
  - accrual_periodstring
    Accrual period. If set to "month", hours_per_month is required. If set to "year", hours_per_year is required
  - accrual_daystring
    Day of the month when accrual happens
  - prorate_on_startboolean
    Whether to prorate time based on start date
- membership_rulesobject
  object
  - countriesArray[String] required
    ISO 3166-1 alpha-2 country codes
  - employment_typesArray[String] required
    Employment type filters

Example response

json

{
  "time_off_policy": {
    "id": 0,
    "organization_id": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "name": "string",
    "created_by_id": 0,
    "auto_add_new_users": false,
    "allow_negative_balances": false,
    "requires_approval": false,
    "balance_rolls_over_annually": false,
    "paid": false,
    "status": "string",
    "policy_type": "string",
    "policy_config": {
      "starting_balance": 0,
      "hours_per": 0,
      "hours_worked": 0,
      "maximum_to_accrue": 0,
      "hours_per_year": 0,
      "hours_per_month": 0,
      "accrual_period": "month",
      "accrual_day": "first_day_of_month",
      "prorate_on_start": false
    },
    "membership_rules": {
      "countries": null,
      "employment_types": null
    }
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Delete time off policy

DELETE/v2/time_off_policies/{time_off_policy_id}

Deletes the time off policy.

A policy cannot be deleted if any of its members have:

paid time off requests,
approved time off requests, or
used time off hours (time off adjustments).

Other balance adjustments (accruals, manual adjustments) do not prevent deletion and are removed along with the policy.

Use the archive endpoint instead to retire a policy that has been used.

Parameters

Name	In	Type	Description
time_off_policy_idrequired	path	integer (int32)	Time off policy ID

Responses

204Deletion successful

object

time_off_policyobject
object
TimeOffPolicy model
- idinteger required
  Time off policy ID
- organization_idinteger required
  Organization ID
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- namestring required
  Time off policy name
- created_by_idinteger
  User ID who created the policy
- auto_add_new_usersboolean required
  Automatically add new members to this policy
- allow_negative_balancesboolean required
  Member can request time off before having the balance for it.
- requires_approvalboolean required
  When false time off requests are automatically approved.
- balance_rolls_over_annuallyboolean required
  balance rolls over annually
- paidboolean required
  When true members will be paid for time off taken.
- statusstring required
  Policy status
- policy_typestring required
  Type of policy
- policy_configobject required
  object
  - starting_balancenumber
    Starting balance (hours)
  - hours_perinteger
    Hours per at amount accrued
  - hours_workedinteger
    Hours worked at amount accrued
  - maximum_to_accrueinteger
    Maximum amount of time off that can be accrued per year. (hours)
  - hours_per_yearinteger
    Hours per year
  - hours_per_monthnumber
    Hours per month
  - accrual_periodstring
    Accrual period. If set to "month", hours_per_month is required. If set to "year", hours_per_year is required
  - accrual_daystring
    Day of the month when accrual happens
  - prorate_on_startboolean
    Whether to prorate time based on start date
- membership_rulesobject
  object
  - countriesArray[String] required
    ISO 3166-1 alpha-2 country codes
  - employment_typesArray[String] required
    Employment type filters

Example response

json

{
  "time_off_policy": {
    "id": 0,
    "organization_id": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "name": "string",
    "created_by_id": 0,
    "auto_add_new_users": false,
    "allow_negative_balances": false,
    "requires_approval": false,
    "balance_rolls_over_annually": false,
    "paid": false,
    "status": "string",
    "policy_type": "string",
    "policy_config": {
      "starting_balance": 0,
      "hours_per": 0,
      "hours_worked": 0,
      "maximum_to_accrue": 0,
      "hours_per_year": 0,
      "hours_per_month": 0,
      "accrual_period": "month",
      "accrual_day": "first_day_of_month",
      "prorate_on_start": false
    },
    "membership_rules": {
      "countries": null,
      "employment_types": null
    }
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Archive time off policy

POST/v2/time_off_policies/{time_off_policy_id}/archive

Archives the time off policy.

Returns the archived time off policy.

Parameters

Name	In	Type	Description
time_off_policy_idrequired	path	integer (int32)	Time off policy ID

Responses

200A time off policy

object

time_off_policyobject
object
TimeOffPolicy model
- idinteger required
  Time off policy ID
- organization_idinteger required
  Organization ID
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- namestring required
  Time off policy name
- created_by_idinteger
  User ID who created the policy
- auto_add_new_usersboolean required
  Automatically add new members to this policy
- allow_negative_balancesboolean required
  Member can request time off before having the balance for it.
- requires_approvalboolean required
  When false time off requests are automatically approved.
- balance_rolls_over_annuallyboolean required
  balance rolls over annually
- paidboolean required
  When true members will be paid for time off taken.
- statusstring required
  Policy status
- policy_typestring required
  Type of policy
- policy_configobject required
  object
  - starting_balancenumber
    Starting balance (hours)
  - hours_perinteger
    Hours per at amount accrued
  - hours_workedinteger
    Hours worked at amount accrued
  - maximum_to_accrueinteger
    Maximum amount of time off that can be accrued per year. (hours)
  - hours_per_yearinteger
    Hours per year
  - hours_per_monthnumber
    Hours per month
  - accrual_periodstring
    Accrual period. If set to "month", hours_per_month is required. If set to "year", hours_per_year is required
  - accrual_daystring
    Day of the month when accrual happens
  - prorate_on_startboolean
    Whether to prorate time based on start date
- membership_rulesobject
  object
  - countriesArray[String] required
    ISO 3166-1 alpha-2 country codes
  - employment_typesArray[String] required
    Employment type filters

Example response

json

{
  "time_off_policy": {
    "id": 0,
    "organization_id": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "name": "string",
    "created_by_id": 0,
    "auto_add_new_users": false,
    "allow_negative_balances": false,
    "requires_approval": false,
    "balance_rolls_over_annually": false,
    "paid": false,
    "status": "string",
    "policy_type": "string",
    "policy_config": {
      "starting_balance": 0,
      "hours_per": 0,
      "hours_worked": 0,
      "maximum_to_accrue": 0,
      "hours_per_year": 0,
      "hours_per_month": 0,
      "accrual_period": "month",
      "accrual_day": "first_day_of_month",
      "prorate_on_start": false
    },
    "membership_rules": {
      "countries": null,
      "employment_types": null
    }
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Restore time off policy

POST/v2/time_off_policies/{time_off_policy_id}/restore

Restores an archived time off policy.

The policy name will be appended with a restoration date suffix.

Returns the restored time off policy.

Parameters

Name	In	Type	Description
time_off_policy_idrequired	path	integer (int32)	Time off policy ID

Responses

200A time off policy

object

time_off_policyobject
object
TimeOffPolicy model
- idinteger required
  Time off policy ID
- organization_idinteger required
  Organization ID
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- namestring required
  Time off policy name
- created_by_idinteger
  User ID who created the policy
- auto_add_new_usersboolean required
  Automatically add new members to this policy
- allow_negative_balancesboolean required
  Member can request time off before having the balance for it.
- requires_approvalboolean required
  When false time off requests are automatically approved.
- balance_rolls_over_annuallyboolean required
  balance rolls over annually
- paidboolean required
  When true members will be paid for time off taken.
- statusstring required
  Policy status
- policy_typestring required
  Type of policy
- policy_configobject required
  object
  - starting_balancenumber
    Starting balance (hours)
  - hours_perinteger
    Hours per at amount accrued
  - hours_workedinteger
    Hours worked at amount accrued
  - maximum_to_accrueinteger
    Maximum amount of time off that can be accrued per year. (hours)
  - hours_per_yearinteger
    Hours per year
  - hours_per_monthnumber
    Hours per month
  - accrual_periodstring
    Accrual period. If set to "month", hours_per_month is required. If set to "year", hours_per_year is required
  - accrual_daystring
    Day of the month when accrual happens
  - prorate_on_startboolean
    Whether to prorate time based on start date
- membership_rulesobject
  object
  - countriesArray[String] required
    ISO 3166-1 alpha-2 country codes
  - employment_typesArray[String] required
    Employment type filters

Example response

json

{
  "time_off_policy": {
    "id": 0,
    "organization_id": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "name": "string",
    "created_by_id": 0,
    "auto_add_new_users": false,
    "allow_negative_balances": false,
    "requires_approval": false,
    "balance_rolls_over_annually": false,
    "paid": false,
    "status": "string",
    "policy_type": "string",
    "policy_config": {
      "starting_balance": 0,
      "hours_per": 0,
      "hours_worked": 0,
      "maximum_to_accrue": 0,
      "hours_per_year": 0,
      "hours_per_month": 0,
      "accrual_period": "month",
      "accrual_day": "first_day_of_month",
      "prorate_on_start": false
    },
    "membership_rules": {
      "countries": null,
      "employment_types": null
    }
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}