Benefit

Benefits are non-monetary compensations provided to employees, such as health insurance, sick time, vacation, personal time off, retirement package, facilities, etc. Benefit object allows you to perform the following operations:

  • Retrieve a specific benefit or a list of benefits
  • Create a benefit
  • Update a benefit
  • Delete a benefit

  • cURL
  • NODE.JS
  • PHP
  • C#
  • PYTHON
  • JAVA
NameDescriptionFormatAttributes
nameName of the benefitstringFilterable, Sortable
accrualMethodDescribes how the accrual-type benefit is earned, whether it is based on the calendar year and the time elapsed till the current date (Calendar), or it is based on approved time entries (Time Card) AccrualMethod
createdByIdIdentifier of the user who created this objectuuidFilterable
createdOnDate and time when this object was created (UTC Now), in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-timeFilterable, Sortable
earnedUnitsType of units earned in the accrual-type benefit within the evaluated period, e.g., Hour or Day. This is used only when the accrual method is calendar-based EarnedUnits
endsOnDate when the fixed-type benefit ends or expires for an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
expiryDateDate when the accrued units that were carried forward expire in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ExpiryType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ExpiryType property is set as ‘Recurring Date’date-time
expiryTypeDescribes when the MaxCarryValue for the accrual-type benefit expires, i.e., when the accrued units that were carried forward are no longer valid, e.g., on the hire date anniversary, a specific date, a recurring date, etc. BenefitResetType
idObject identifieruuidFilterable
isCompensationIndicates whether the fixed-type benefit is being offered as part of the compensation (salary) or notboolean
lastUpdatedLast updated date and time value of this object in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-timeFilterable, Sortable
lastUpdatedByIdIdentifier of the user who last updated this objectuuidFilterable
maxAccruedValueMaximum value of units an employee can accrue during a benefit earning perioddouble
maxCarryValueMaximum value of accrued units that can be carried forward to the next benefit earning period when the current period endsdouble
maxValueMaximum amount allowed for the fixed-type benefitdouble
memoRecords any extra information of the benefit for recapitulationstring
objectStateRepresents the state of the object. e.g., new, unchanged, modified or deleted ObjectState
periodTime for which the fixed-type benefit is provided, e.g., Day, Week, Month, etc. PeriodUnits
realizationDateDate when the full benefit quota becomes available for use in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the RealizationType property is set as 'Specific Date'date-time
realizationTypeDescribes when the accrual-type benefit can be used, whether on the go as the benefits are earned, at the beginning or end of the benefit earning period, or at a specific date RealizationType
resetDateDate when the accrual-type benefit balance is reset to zero in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ResetType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ResetType property is set as ‘Recurring Date’date-time
resetTypeDescribes when the accrual-type benefit expires, i.e., the benefit balance resets to zero, e.g., on the hire date anniversary, a specfic date, a recurring date, etc. BenefitResetType
rules []List of benefit earning rules for accrual-type benefits BenefitRule
startsOnDate when the fixed-type benefit is assigned to an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
statusCurrent status of the benefit, e.g., Active or Inactive Status
subTypeSub-type of the accrual-type benefit, whether Sick or Vacation BenefitSubType
tokenRepresents the token for update operationsint32
typeType of benefit, whether accrual (which allows you to define accrual rules and manage earned versus burned benefits) or fixed (which only needs to be recorded from time to time and does not have any accrual rules) BenefitType
unitsTime frame for which the earned units are analyzed, i.e., the period an employee must work in the company to earn a particular accrual-type benefit PeriodUnits
valueAmount for the fixed-type benefit, say bonus amount per yeardouble
versionImplements concurrency on this objectbyte

Use this method to retrieve a list of benefits. You can optionally pass where, orderBy, and page as query parameters to filter the result. Use the fields parameter to request a subset of the model. By default, a complete model is returned. The expand parameter is used to request nested properties in the model.

Request URL
base_url/hr/benefit

Method Overview

HTTP Method:

GET

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Headers:

Access Token

Module:

Benefit

Required Scopes:

read:core

Required Subscription:

View Subscription


Request Parameters asterisk denotes required
NameParameter TypeDescriptionFormat
fields Query Specifies the model properties you want in the response bodystring
where Query Specifies only those records that match an expression in the querystring
orderBy Query Specifies the order of the recordsstring
page Query Specifies the page number and number of records on each pagestring
expand Query Specifies the nested model properties you want in the response bodystring
Response Body
NameDescriptionFormat
name Name of the benefitstring
accrualMethod Describes how the accrual-type benefit is earned, whether it is based on the calendar year and the time elapsed till the current date (Calendar), or it is based on approved time entries (Time Card) AccrualMethod
createdById Identifier of the user who created this objectuuid
createdOn Date and time when this object was created (UTC Now), in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
earnedUnits Type of units earned in the accrual-type benefit within the evaluated period, e.g., Hour or Day. This is used only when the accrual method is calendar-based EarnedUnits
endsOn Date when the fixed-type benefit ends or expires for an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
expiryDate Date when the accrued units that were carried forward expire in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ExpiryType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ExpiryType property is set as ‘Recurring Date’date-time
expiryType Describes when the MaxCarryValue for the accrual-type benefit expires, i.e., when the accrued units that were carried forward are no longer valid, e.g., on the hire date anniversary, a specific date, a recurring date, etc. BenefitResetType
id Object identifieruuid
isCompensation Indicates whether the fixed-type benefit is being offered as part of the compensation (salary) or notboolean
lastUpdated Last updated date and time value of this object in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
lastUpdatedById Identifier of the user who last updated this objectuuid
maxAccruedValue Maximum value of units an employee can accrue during a benefit earning perioddouble
maxCarryValue Maximum value of accrued units that can be carried forward to the next benefit earning period when the current period endsdouble
maxValue Maximum amount allowed for the fixed-type benefitdouble
memo Records any extra information of the benefit for recapitulationstring
objectState Represents the state of the object. e.g., new, unchanged, modified or deleted ObjectState
period Time for which the fixed-type benefit is provided, e.g., Day, Week, Month, etc. PeriodUnits
realizationDate Date when the full benefit quota becomes available for use in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the RealizationType property is set as 'Specific Date'date-time
realizationType Describes when the accrual-type benefit can be used, whether on the go as the benefits are earned, at the beginning or end of the benefit earning period, or at a specific date RealizationType
resetDate Date when the accrual-type benefit balance is reset to zero in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ResetType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ResetType property is set as ‘Recurring Date’date-time
resetType Describes when the accrual-type benefit expires, i.e., the benefit balance resets to zero, e.g., on the hire date anniversary, a specfic date, a recurring date, etc. BenefitResetType
rules []List of benefit earning rules for accrual-type benefits BenefitRule
startsOn Date when the fixed-type benefit is assigned to an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
status Current status of the benefit, e.g., Active or Inactive Status
subType Sub-type of the accrual-type benefit, whether Sick or Vacation BenefitSubType
token Represents the token for update operationsint32
type Type of benefit, whether accrual (which allows you to define accrual rules and manage earned versus burned benefits) or fixed (which only needs to be recorded from time to time and does not have any accrual rules) BenefitType
units Time frame for which the earned units are analyzed, i.e., the period an employee must work in the company to earn a particular accrual-type benefit PeriodUnits
value Amount for the fixed-type benefit, say bonus amount per yeardouble
version Implements concurrency on this objectbyte
Example Request
Example Response
[
  {
    "name": "Benefit",
    "accrualMethod": null,
    "createdById": "9f4f1859-d386-48de-b981-d1131d300a50",
    "createdOn": "2021-11-09T09:09:47Z",
    "earnedUnits": null,
    "endsOn": "2021-11-09T09:09:47Z",
    "expiryDate": "2021-11-09T09:09:47Z",
    "expiryType": null,
    "id": "5840a031-39d5-42b7-af88-1c8d6226439c",
    "isCompensation": true,
    "lastUpdated": "2021-11-09T09:09:47Z",
    "lastUpdatedById": "ce9a4f21-6104-4e79-9b93-ceae2f35d8d1",
    "maxAccruedValue": 1,
    "maxCarryValue": 1,
    "maxValue": 1,
    "memo": "memo",
    "objectState": null,
    "period": null,
    "realizationDate": "2021-11-09T09:09:47Z",
    "realizationType": null,
    "resetDate": "2021-11-09T09:09:47Z",
    "resetType": null,
    "rules": [
      {
        "benefitId": "e46eb703-6e0f-4f45-8a0c-986ba28b3f7c",
        "createdById": "e9c39d1e-c0b5-4ffd-aeec-e86b142b603e",
        "createdOn": "2021-11-09T09:09:47Z",
        "id": "fa509d44-f9ee-4cfe-b12b-f8d5848bc209",
        "lastUpdated": "2021-11-09T09:09:47Z",
        "lastUpdatedById": "ea71bad6-4473-4882-85cc-f462ac2116b5",
        "objectState": null,
        "periodUnits": 1,
        "token": 0,
        "unitsEarned": 1,
        "version": "U3dhZ2dlciByb2Nrcw=="
      }
    ],
    "startsOn": "2021-11-09T09:09:47Z",
    "status": null,
    "subType": null,
    "token": 0,
    "type": null,
    "units": null,
    "value": 1,
    "version": "U3dhZ2dlciByb2Nrcw=="
  }
]

Use this method to retrieve a specific benefit. Pass id as the parameter.

Request URL
base_url/hr/benefit/{id}

Method Overview

HTTP Method:

GET

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Headers:

Access Token

Module:

Benefit

Required Scopes:

read:core

Required Subscription:

View Subscription


Request Parameters asterisk denotes required
NameParameter TypeDescriptionFormat
id Path Benefit identifierstring
Response Body
NameDescriptionFormat
name Name of the benefitstring
accrualMethod Describes how the accrual-type benefit is earned, whether it is based on the calendar year and the time elapsed till the current date (Calendar), or it is based on approved time entries (Time Card) AccrualMethod
createdById Identifier of the user who created this objectuuid
createdOn Date and time when this object was created (UTC Now), in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
earnedUnits Type of units earned in the accrual-type benefit within the evaluated period, e.g., Hour or Day. This is used only when the accrual method is calendar-based EarnedUnits
endsOn Date when the fixed-type benefit ends or expires for an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
expiryDate Date when the accrued units that were carried forward expire in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ExpiryType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ExpiryType property is set as ‘Recurring Date’date-time
expiryType Describes when the MaxCarryValue for the accrual-type benefit expires, i.e., when the accrued units that were carried forward are no longer valid, e.g., on the hire date anniversary, a specific date, a recurring date, etc. BenefitResetType
id Object identifieruuid
isCompensation Indicates whether the fixed-type benefit is being offered as part of the compensation (salary) or notboolean
lastUpdated Last updated date and time value of this object in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
lastUpdatedById Identifier of the user who last updated this objectuuid
maxAccruedValue Maximum value of units an employee can accrue during a benefit earning perioddouble
maxCarryValue Maximum value of accrued units that can be carried forward to the next benefit earning period when the current period endsdouble
maxValue Maximum amount allowed for the fixed-type benefitdouble
memo Records any extra information of the benefit for recapitulationstring
objectState Represents the state of the object. e.g., new, unchanged, modified or deleted ObjectState
period Time for which the fixed-type benefit is provided, e.g., Day, Week, Month, etc. PeriodUnits
realizationDate Date when the full benefit quota becomes available for use in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the RealizationType property is set as 'Specific Date'date-time
realizationType Describes when the accrual-type benefit can be used, whether on the go as the benefits are earned, at the beginning or end of the benefit earning period, or at a specific date RealizationType
resetDate Date when the accrual-type benefit balance is reset to zero in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ResetType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ResetType property is set as ‘Recurring Date’date-time
resetType Describes when the accrual-type benefit expires, i.e., the benefit balance resets to zero, e.g., on the hire date anniversary, a specfic date, a recurring date, etc. BenefitResetType
rules []List of benefit earning rules for accrual-type benefits BenefitRule
startsOn Date when the fixed-type benefit is assigned to an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
status Current status of the benefit, e.g., Active or Inactive Status
subType Sub-type of the accrual-type benefit, whether Sick or Vacation BenefitSubType
token Represents the token for update operationsint32
type Type of benefit, whether accrual (which allows you to define accrual rules and manage earned versus burned benefits) or fixed (which only needs to be recorded from time to time and does not have any accrual rules) BenefitType
units Time frame for which the earned units are analyzed, i.e., the period an employee must work in the company to earn a particular accrual-type benefit PeriodUnits
value Amount for the fixed-type benefit, say bonus amount per yeardouble
version Implements concurrency on this objectbyte
Example Request
Example Response
{
  "name": "Benefit",
  "accrualMethod": null,
  "createdById": "d396f7fb-3064-402b-aefd-d4f888617394",
  "createdOn": "2021-11-09T09:09:47Z",
  "earnedUnits": null,
  "endsOn": "2021-11-09T09:09:47Z",
  "expiryDate": "2021-11-09T09:09:47Z",
  "expiryType": null,
  "id": "3ff6bc56-ba40-47b4-b6ab-6b1ef3b52c50",
  "isCompensation": true,
  "lastUpdated": "2021-11-09T09:09:47Z",
  "lastUpdatedById": "7dbeb2d4-d7d9-47c6-acd4-249cf1ccd757",
  "maxAccruedValue": 1,
  "maxCarryValue": 1,
  "maxValue": 1,
  "memo": "memo",
  "objectState": null,
  "period": null,
  "realizationDate": "2021-11-09T09:09:47Z",
  "realizationType": null,
  "resetDate": "2021-11-09T09:09:47Z",
  "resetType": null,
  "rules": [
    {
      "benefitId": "6ed917d2-ca24-4003-95cc-081b3507ca03",
      "createdById": "60cab4b0-f927-4461-bb6e-3a2b9fcc44c9",
      "createdOn": "2021-11-09T09:09:47Z",
      "id": "2fe4e9c3-9095-45e7-adb6-e6dd27d4c30d",
      "lastUpdated": "2021-11-09T09:09:47Z",
      "lastUpdatedById": "c5cd2b0c-ec0e-4791-b0b7-e4c0fa1aafa7",
      "objectState": null,
      "periodUnits": 1,
      "token": 0,
      "unitsEarned": 1,
      "version": "U3dhZ2dlciByb2Nrcw=="
    }
  ],
  "startsOn": "2021-11-09T09:09:47Z",
  "status": null,
  "subType": null,
  "token": 0,
  "type": null,
  "units": null,
  "value": 1,
  "version": "U3dhZ2dlciByb2Nrcw=="
}

Use this method to save a benefit. Pass benefit as the parameter.

Request URL
base_url/hr/benefit

Method Overview

HTTP Method:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Headers:

Access Token

Module:

Benefit

Required Scopes:

readwrite:core

Required Subscription:

View Subscription


Request Parameters asterisk denotes required
NameParameter TypeDescriptionFormat
body Body Benefit objectBenefit
Response Body
NameDescriptionFormat
name Name of the benefitstring
accrualMethod Describes how the accrual-type benefit is earned, whether it is based on the calendar year and the time elapsed till the current date (Calendar), or it is based on approved time entries (Time Card) AccrualMethod
createdById Identifier of the user who created this objectuuid
createdOn Date and time when this object was created (UTC Now), in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
earnedUnits Type of units earned in the accrual-type benefit within the evaluated period, e.g., Hour or Day. This is used only when the accrual method is calendar-based EarnedUnits
endsOn Date when the fixed-type benefit ends or expires for an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
expiryDate Date when the accrued units that were carried forward expire in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ExpiryType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ExpiryType property is set as ‘Recurring Date’date-time
expiryType Describes when the MaxCarryValue for the accrual-type benefit expires, i.e., when the accrued units that were carried forward are no longer valid, e.g., on the hire date anniversary, a specific date, a recurring date, etc. BenefitResetType
id Object identifieruuid
isCompensation Indicates whether the fixed-type benefit is being offered as part of the compensation (salary) or notboolean
lastUpdated Last updated date and time value of this object in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
lastUpdatedById Identifier of the user who last updated this objectuuid
maxAccruedValue Maximum value of units an employee can accrue during a benefit earning perioddouble
maxCarryValue Maximum value of accrued units that can be carried forward to the next benefit earning period when the current period endsdouble
maxValue Maximum amount allowed for the fixed-type benefitdouble
memo Records any extra information of the benefit for recapitulationstring
objectState Represents the state of the object. e.g., new, unchanged, modified or deleted ObjectState
period Time for which the fixed-type benefit is provided, e.g., Day, Week, Month, etc. PeriodUnits
realizationDate Date when the full benefit quota becomes available for use in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the RealizationType property is set as 'Specific Date'date-time
realizationType Describes when the accrual-type benefit can be used, whether on the go as the benefits are earned, at the beginning or end of the benefit earning period, or at a specific date RealizationType
resetDate Date when the accrual-type benefit balance is reset to zero in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ResetType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ResetType property is set as ‘Recurring Date’date-time
resetType Describes when the accrual-type benefit expires, i.e., the benefit balance resets to zero, e.g., on the hire date anniversary, a specfic date, a recurring date, etc. BenefitResetType
rules []List of benefit earning rules for accrual-type benefits BenefitRule
startsOn Date when the fixed-type benefit is assigned to an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
status Current status of the benefit, e.g., Active or Inactive Status
subType Sub-type of the accrual-type benefit, whether Sick or Vacation BenefitSubType
token Represents the token for update operationsint32
type Type of benefit, whether accrual (which allows you to define accrual rules and manage earned versus burned benefits) or fixed (which only needs to be recorded from time to time and does not have any accrual rules) BenefitType
units Time frame for which the earned units are analyzed, i.e., the period an employee must work in the company to earn a particular accrual-type benefit PeriodUnits
value Amount for the fixed-type benefit, say bonus amount per yeardouble
version Implements concurrency on this objectbyte
Example Request
Example Response
{
  "name": "Benefit",
  "accrualMethod": null,
  "createdById": "66a9f1d1-4215-4d7a-a8d2-597cb02b7d51",
  "createdOn": "2021-11-09T09:09:47Z",
  "earnedUnits": null,
  "endsOn": "2021-11-09T09:09:47Z",
  "expiryDate": "2021-11-09T09:09:47Z",
  "expiryType": null,
  "id": "3cd0eab5-a6e2-427c-8be3-7addb8b37946",
  "isCompensation": true,
  "lastUpdated": "2021-11-09T09:09:47Z",
  "lastUpdatedById": "a3755d51-9f0c-4e7a-9076-1ef0e835b286",
  "maxAccruedValue": 1,
  "maxCarryValue": 1,
  "maxValue": 1,
  "memo": "memo",
  "objectState": null,
  "period": null,
  "realizationDate": "2021-11-09T09:09:47Z",
  "realizationType": null,
  "resetDate": "2021-11-09T09:09:47Z",
  "resetType": null,
  "rules": [
    {
      "benefitId": "8928c5ab-0160-45f1-9189-ff18140d7ed5",
      "createdById": "5f505934-80e3-469f-a1c4-6e05da603633",
      "createdOn": "2021-11-09T09:09:47Z",
      "id": "b3f0d67f-9f73-437a-8058-11302a29935d",
      "lastUpdated": "2021-11-09T09:09:47Z",
      "lastUpdatedById": "96e3b8a6-dbb2-492f-abe3-6bddc8d3e18d",
      "objectState": null,
      "periodUnits": 1,
      "token": 0,
      "unitsEarned": 1,
      "version": "U3dhZ2dlciByb2Nrcw=="
    }
  ],
  "startsOn": "2021-11-09T09:09:47Z",
  "status": null,
  "subType": null,
  "token": 0,
  "type": null,
  "units": null,
  "value": 1,
  "version": "U3dhZ2dlciByb2Nrcw=="
}

Use this method to save multiple benefits. Pass model as the parameter.

Request URL
base_url/hr/benefit/batch

Method Overview

HTTP Method:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Headers:

Access Token

Module:

Benefit

Required Scopes:

readwrite:core

Required Subscription:

View Subscription


Request Parameters asterisk denotes required
NameParameter TypeDescriptionFormat
body Body Benefit objectBenefitBatchRequest
Response Body
NameDescriptionFormat
batchSize Represents the number of entities in a batchint64
createdById Identifier of the user who created this objectuuid
createdOn Date and time when this object was created (UTC Now), in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
id Object identifieruuid
lastUpdated Last updated date and time value of this object in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
lastUpdatedById Identifier of the user who last updated this objectuuid
objectState Represents the state of the object. e.g., new, unchanged, modified or deleted ObjectState
progress Represents the total number of entities processedint64
status Represents the status of a job e.g., ready, running, completed, or terminatedstring
token Represents the token for update operationsint32
type Represents the type of a job e.g., create, update, or deletestring
version Implements concurrency on this objectbyte
Example Request
Example Response
{
  "batchSize": 0,
  "createdById": "bc1a203f-225f-41a8-ab03-e4df45de1438",
  "createdOn": "2021-11-09T09:09:47Z",
  "id": "8138fa79-e969-4153-b67d-37b262e9fba8",
  "lastUpdated": "2021-11-09T09:09:47Z",
  "lastUpdatedById": "86430ba5-a97d-4464-b39f-07611cb6e0d1",
  "objectState": null,
  "progress": 0,
  "status": "status",
  "token": 0,
  "type": "type",
  "version": "U3dhZ2dlciByb2Nrcw=="
}

Use this method to update a benefit. Pass id and benefit as the parameters.

Request URL
base_url/hr/benefit/{id}

Method Overview

HTTP Method:

PUT

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Headers:

Access Token

Module:

Benefit

Required Scopes:

readwrite:core

Required Subscription:

View Subscription


Request Parameters asterisk denotes required
NameParameter TypeDescriptionFormat
id Path Benefit identifierstring
body Body Benefit objectBenefit
Response Body
NameDescriptionFormat
name Name of the benefitstring
accrualMethod Describes how the accrual-type benefit is earned, whether it is based on the calendar year and the time elapsed till the current date (Calendar), or it is based on approved time entries (Time Card) AccrualMethod
createdById Identifier of the user who created this objectuuid
createdOn Date and time when this object was created (UTC Now), in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
earnedUnits Type of units earned in the accrual-type benefit within the evaluated period, e.g., Hour or Day. This is used only when the accrual method is calendar-based EarnedUnits
endsOn Date when the fixed-type benefit ends or expires for an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
expiryDate Date when the accrued units that were carried forward expire in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ExpiryType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ExpiryType property is set as ‘Recurring Date’date-time
expiryType Describes when the MaxCarryValue for the accrual-type benefit expires, i.e., when the accrued units that were carried forward are no longer valid, e.g., on the hire date anniversary, a specific date, a recurring date, etc. BenefitResetType
id Object identifieruuid
isCompensation Indicates whether the fixed-type benefit is being offered as part of the compensation (salary) or notboolean
lastUpdated Last updated date and time value of this object in ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ssdate-time
lastUpdatedById Identifier of the user who last updated this objectuuid
maxAccruedValue Maximum value of units an employee can accrue during a benefit earning perioddouble
maxCarryValue Maximum value of accrued units that can be carried forward to the next benefit earning period when the current period endsdouble
maxValue Maximum amount allowed for the fixed-type benefitdouble
memo Records any extra information of the benefit for recapitulationstring
objectState Represents the state of the object. e.g., new, unchanged, modified or deleted ObjectState
period Time for which the fixed-type benefit is provided, e.g., Day, Week, Month, etc. PeriodUnits
realizationDate Date when the full benefit quota becomes available for use in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the RealizationType property is set as 'Specific Date'date-time
realizationType Describes when the accrual-type benefit can be used, whether on the go as the benefits are earned, at the beginning or end of the benefit earning period, or at a specific date RealizationType
resetDate Date when the accrual-type benefit balance is reset to zero in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ss. This is used when the ResetType property is set as 'Specific Date'. Also, the day and month from this property are used for the recurrence when the ResetType property is set as ‘Recurring Date’date-time
resetType Describes when the accrual-type benefit expires, i.e., the benefit balance resets to zero, e.g., on the hire date anniversary, a specfic date, a recurring date, etc. BenefitResetType
rules []List of benefit earning rules for accrual-type benefits BenefitRule
startsOn Date when the fixed-type benefit is assigned to an employee in ISO 8601 date-time format, such as YYYY-MM-DDThh:mm:ssdate-time
status Current status of the benefit, e.g., Active or Inactive Status
subType Sub-type of the accrual-type benefit, whether Sick or Vacation BenefitSubType
token Represents the token for update operationsint32
type Type of benefit, whether accrual (which allows you to define accrual rules and manage earned versus burned benefits) or fixed (which only needs to be recorded from time to time and does not have any accrual rules) BenefitType
units Time frame for which the earned units are analyzed, i.e., the period an employee must work in the company to earn a particular accrual-type benefit PeriodUnits
value Amount for the fixed-type benefit, say bonus amount per yeardouble
version Implements concurrency on this objectbyte
Example Request
Example Response
{
  "name": "Benefit",
  "accrualMethod": null,
  "createdById": "fc263f68-5f01-4a17-a488-8c1c79f31f5a",
  "createdOn": "2021-11-09T09:09:47Z",
  "earnedUnits": null,
  "endsOn": "2021-11-09T09:09:47Z",
  "expiryDate": "2021-11-09T09:09:47Z",
  "expiryType": null,
  "id": "d9c6700c-b422-4434-8eed-9d526862595c",
  "isCompensation": true,
  "lastUpdated": "2021-11-09T09:09:47Z",
  "lastUpdatedById": "481dca6c-e91a-42ea-97ba-4fb86a0557e3",
  "maxAccruedValue": 1,
  "maxCarryValue": 1,
  "maxValue": 1,
  "memo": "memo",
  "objectState": null,
  "period": null,
  "realizationDate": "2021-11-09T09:09:47Z",
  "realizationType": null,
  "resetDate": "2021-11-09T09:09:47Z",
  "resetType": null,
  "rules": [
    {
      "benefitId": "8850a2d2-7688-40a9-a5fe-0e478de715f8",
      "createdById": "6fd2ebb7-d854-444c-b952-e23f0691ddd5",
      "createdOn": "2021-11-09T09:09:47Z",
      "id": "8b39bf99-2f2a-4a6b-a2f8-d1eba8f92ed4",
      "lastUpdated": "2021-11-09T09:09:47Z",
      "lastUpdatedById": "02b41b7e-dd73-42f0-b4a9-b6804573b55d",
      "objectState": null,
      "periodUnits": 1,
      "token": 0,
      "unitsEarned": 1,
      "version": "U3dhZ2dlciByb2Nrcw=="
    }
  ],
  "startsOn": "2021-11-09T09:09:47Z",
  "status": null,
  "subType": null,
  "token": 0,
  "type": null,
  "units": null,
  "value": 1,
  "version": "U3dhZ2dlciByb2Nrcw=="
}

Use this method to delete a specific benefit. Pass id as the parameter.

Request URL
base_url/hr/benefit/{id}

Method Overview

HTTP Method:

DELETE

Content Type:

application/json

Response Format:

N/A

Requires Authentication?

Yes

Headers:

Access Token

Required Scopes:

readwrite:core

Required Subscription:

View Subscription


Request Parameters asterisk denotes required
NameParameter TypeDescriptionFormat
id Path Benefit identifierstring
Example Request

Use this method to perform partial modifications to a benefit. Pass id and patch document as parameters.

Request URL
base_url/hr/benefit/{id}

Method Overview

HTTP Method:

PATCH

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Headers:

Access Token

Module:

Benefit

Required Scopes:

readwrite:core

Required Subscription:

View Subscription


Request Parameters asterisk denotes required
NameParameter TypeDescriptionFormat
id Path Benefit identifierstring
body Body A document containing an array of objects with each object representing a single operation to be performedBenefitPatchDocument
Response Body
NameDescriptionFormat
Example Request
Example Response