Dartmouth API Developer Portal

Payroll Deduction

The Payroll Deduction API is available for authorized source systems to transmit/cancel payroll dedections for a Dartmouth employee. Application to use this service must be approved by the Human Resources office. Transactions posted to this service are monitored and audited by the Human Resources office on a daily basis. Unauthorized use or attempted use of this service will be considered a major violation of the Dartmouth Code of Conduct/and or possibly a criminal violation and be adjucated accordingly.

Notes on usage

The API takes in a transaction_set of deductions. A transaction set can be one or more payroll deductions transactions. The set does not imply any type of integrity across the transactions other than they all are coming from one source system.

Each transaction in the set stands alone in terms of processing acceptance or failure. One incorrect transaction does not invalidate the entire set. Use of the posting_type attribute as either TRIAL or COMMIT will determine if the set is ultimately committed or rolled back.

Each payroll deduction is uniquely identified in the payroll system by source system, netid affected and the deduction type.

Deduction Types

Deduction types are pre-configured in the payroll system and can be specific to each source system. Examples shown below are for illustration purposes only. Contact the Human Resources office to have deduction types set up and configured for your system.

Action Types

One of 4 action types can be supplied for each payroll deduction transaction. The possible values are:

action_type	Description
add	this is a new payroll deduction for this source system/employee
cancel	an existing payroll deduction for this source system/employee should be cancelled
replace	an existing payroll deduction for this source system/employee should be replaced
adjust	need definition here

Pay Period Types

Pay periods that apply to the payroll deduction should be specified for each payroll deduction transaction. The possible values are:

action_type	Description
any	this payroll deduction can apply to any payroll period across fiscal and calendar boundaries
fiscal	this payroll deduction can only apply with a single fiscal year period
calendar	this payroll deduction can only apply with a single calendar year period

what if calendar specified and number of pay periods is 36?

Maximum Pay Periods per Month

For bi-weekly payroll employees, there are sometimes 2 or 3 pay periods within a calendar month. This attribute specifies the maximum number of pay periods in the month that this payroll deduction can apply.

If 1 is specified then a payroll deduction will occur once per month regardless of how many periods are in the month.
If 2 is specified then the payroll deducation can apply at most to 2 pay periods in a 3 pay period month.
If 3 is specified, then the payroll deduction is applied to each successive pay period regardless of how many occur in the month.

Transaction Set Request

Request

POST /api/human_resources/payroll/deduction_batch_request

Required Scope

urn:dartmouth:human_resources.payroll.deduction_batch_request:write

Parameters

None

Body

Transaction set request payload (see example below)

Returns

Status Code	Description
202	The POST request has been accepted and has been handed off to the background processor

Sample Request

https://api.dartmouth.edu/api/human_resources/payroll/deduction_batch_request

POST request with example body

{
  "billing_type":"Payroll Deduction",
  "posting_type":"TRIAL",
  "source_name":"SYSTEM_XYZ",
  "transaction_set_name":"Monthly October 2018 Billing for System XYZ",
  "transactions":[
    {
      "source_transaction_id":"818261",
      "deduction_type": "computer_purchase",
      "action": "add",
      "netid": "d22970x",
      "amount": 1772.14,
      "period_type": "any",
      "number_of_pay_periods": 5,
      "max_pay_periods_per_month": 3,
      "effective_date":"2018-11-01T00:00:00Z"
    },
    {
      "source_transaction_id":"818272",
      "deduction_type": "parking",
      "action": "add",
      "netid": "f003xnh",
      "amount": 100.00,
      "period_type": "any",
      "number_of_pay_periods": 12,
      "max_pay_periods_per_month": 3,
      "effective_date":"2018-11-01T00:00:00Z"
    }
  ]
}

Main Body attributes

All of the following attributes are required.

Field	Type	Description
billing_type	string	currently must be coded as "Payroll Deduction" as the only available billing type. Future use.
posting_type	string	set to TRIAL for a pre-check of the set, COMMIT to send the set to HRS if passes integrity checks
source_name	string	assigned source name (by central accounting) of the system posting the set
transaction_set_name	string	a descriptive name
transactions	array	the array of line transactions as described in the next section

Transactions Attributes

Field	Type	Required/Optional	Description
source_transaction_id	string	required	an id that will allow the transaction to be traced back into the source system (system dependent)
deduction_type	string	required	only predefined types are allowed
action	string	required	can be one of the following values `add`, `cancel` or `replace` what is `adjust`??
netid	string	required	the netid of the employee this transaction affects
amount	number	required	the amount of the transaction
period_type	string	optional	can be one of the following values `any`, `fiscal`, `calendar`, if not specified defaults to `any`
number_of_pay_periods	number	required	the number of pay periods this amount should be spread across
effective_date	string	required	string in ISO8601 format specifies when the deduction becomes effective, if null defaults to system date

would a comment or description be useful??

Returns

Status Code	Description
202	The set has been accepted

{
  "id": "6806B629F89F22E0E0538801120A903F",
  "source_name": "System_XYZ",
  "transaction_set_name": "Monthly October 2018 Billing for System XYZ",
  "posting_type": null,
  "status": "Accepted",
  "message": null,
  "number_of_transactions": null,
  "link": "https://api.dartmouth.edu/api/human_resources/payroll/deduction_batch_request/6806B629F89F22E0E0538801120A903F",
  "is_completed": false,
  "is_error_free": false,
  "submit_time": "2018-03-22T19:57:03Z",
  "completion_time": null,
  "elapsed_minutes": 0,
  "line_errors": []
}

Field	Type	Description
id	string	the id you can use on subsequent requests for getting information about the status of the set
source_tracking_id	string	the id in the HRS system that eventually will identify your set `not sure this applies`
source_name	string	the source name
transaction_set_name	string	the set name
posting_type	string	the posting type of the set
status	string	current status of the background set processing. Values can be
message	string	message giving additional information about status. This message is suitable for display to an end user
number_of_transactions	number	the number of line transactions found in the set
link	string	the url to follow to get information about the status of the set
is_completed	boolean	true when background processing has completed, false otherwise
is_error_free	boolean	null if is_completed flag is false. When is_completed is true, a true in this attribute tells you if the set passed all integrity checks, false otherwise
submit_time	string	date/time set submitted for backend procesing in ISO8601 format
completion_time	string	date/time set processing completed
elapsed_minutes	number	elapsed minutes between submit_time and completion_time
line_errors	array	an array of line errors (if any) encountered, otherwise an empty array ([])

Get Processing Status

This call can be used at any time to get the current status of the set. The status field can return the following values and meanings:

Status	Description
Accepted	the transaction set has been accepted for further processing
Processing	the transaction set is currently being processed
Trial Success	the transaction set has run through a TRIAL processing with no errors encountered
Commit Success	the transaction set has run through a COMMIT processing with no errors encountered
Trial Error	the transaction set has run through a TRIAL processing with one or more errors encountered
Commit Error	the transaction set has run through a COMMIT processing with one or more errors encountered

Request

GET /api/human_resources/payroll/deduction_batch_request/{id}

Required Scope

urn:dartmouth:human_resources.payroll.deduction_batch_request:write

Parameters

Field	Type	Description
id	string	the id of the set

Returns

Status Code	Description
200	The status of the set is returned
404	Not found. The {id} does not reference a valid set id

Sample Request

GET https://api.dartmouth.edu/api/human_resources/payroll/deduction_batch_request/63d2f7a7a4c4d9052cf5b4b8

Sample Return

{
    "batch_id": "63d2f7a7a4c4d9052cf5b4b8",
    "source_name": "SYSTEM_XYZ",
    "transaction_set_name": "Monthly October 2018 Billing for System XYZ",
    "posting_type": "TRIAL",
    "status": "Trial Success",
    "message": "2 transactions accepted.  0 in error.",
    "number_of_transactions": 2,
    "is_completed": true,
    "is_error_free": true,
    "submit_time": "2023-01-26T21:59:03Z",
    "completion_time": "2023-01-26T21:59:04.078461Z",
    "elapsed_seconds": 1,
    "transaction_errors": []
}

Sample Return with Line Errors

{
  "batch_id": "63d2f21a8954ba5c8eb5c643",
  "source_name": "SYSTEM_XYZ",
  "transaction_set_name": "Monthly October 2018 Billing for System XYZ",
  "posting_type": "TRIAL",
  "status": "Trial Error",
  "message": "0 transactions accepted.  2 in error.",
  "number_of_transactions": 2,
  "is_completed": true,
  "is_error_free": false,
  "submit_time": "2023-01-26T21:35:22Z",
  "completion_time": "2023-01-26T21:35:23.492835Z",
  "elapsed_seconds": 1,
  "transaction_errors": [
      {
          "line_number": 0,
          "source_transaction_id": "SYSTEM_XYZ",
          "error_message": {
              "error_message": [
                  "Employee NetID D22970X is not active on 01-NOV-2018"
              ]
          }
      },
      {
          "line_number": 1,
          "source_transaction_id": "SYSTEM_XYZ",
          "error_message": {
              "error_message": [
                  "Employee NetID F003XNH is not active on 01-NOV-2018"
              ]
          }
      }
  ]
}

Get Postings History

This call can be used at any time to get status of previously-submitted set postings.

Request

GET /api/human_resources/payroll/deduction_batch_request

Required Scope

(none)

Parameters

Field	Type	required	Description
source_name	string	optional	the source_name of the set
submit_date	string	optional	the date the set was submitted (yyyy-mm-dd)

Note on usage

This request only returns setes of deductions for the current submitter. If no filter parameters are supplied then all sets are returned.

Returns

Status Code	Description
200	All postings that qualify based on query parameters are returned

Sample Request

GET https://api.dartmouth.edu/api/human_resources/payroll/deduction_batch_request?source_name=SYSTEM_XYZ&submit_date=2018-10-13

Sample Return

[
  {
    "submit_time": "2018-10-13T19:08:40Z",
    "set_id": "703985C52696B553E0538002120A1A2C",
    "current_status": "Error",
    "posting_type": "TRIAL",
    "message": "5 transactions accepted.  1 transactions in error.",
    "set_name": "Monthly October 2018 Billing for System XYZ",
    "source_name": "SYSTEM_XYZ"
  },
  {
    "submit_time": "2018-10-13T23:50:48",
    "set_id": "703973E0B2DEAD05E0538002120AD0B4",
    "current_status": "Commit Success",
    "posting_type": "COMMIT",
    "message": null,
    "set_name": "Monthly September 2018 Billing for System XYZ",
    "source_name": "SYSTEM_XYZ"
  }
]