The quick way to import pay via the API

---

Unlike other blog posts, this one is going to get quite technical.
If you don’t know your JSON from your XML then this one might not be for you.

Importing Hours Worked

When you’re integrating your platform with our payroll API, a very common requirement is to update the pay for employees – often in terms of hours worked – from data held in your own system.

As a developer it’d be fair for you to assume that the way to do this is to find the currently open payrun, find the relevant entry, retrieve it, change it and send it back to us. Then repeat the process for each employee

Whilst that would certainly work, we have a quicker way.

A Quicker Way

The API call we’ll look at now is ImportPay. This is the same API call that the web application makes when a user imports a CSV file.

With this call you can update the payments for multiple employees in one go. You don’t need to know which period (week number or month number) you’re updating as it’ll just update the currently open period.

You submit an array of PayOptionsImport, one for each employee you want to update.
Any employees that are on the payrun but not included in the model you submit to the API will remain unchanged, so you can update as many or as few employees as you like.

As well as setting the basic pay amount for the period (either as a set amount or as a multiple of hours/days) you can also add as many additional lines as you like.

There’s also full support for the recently introduced tags feature.

[
 {
  "payrollCode": "2",
  "payAmount": 12.75,
  "basis": "Hourly",
  "payCode": "BASIC",
  "payAmountMultiplier": 40,
  "lines": [{
   "rate": 25.50,
   "multiplier": 5,
   "description": "Overtime",
   "code": "OTIME",
   "tags": ["CLIENT1","LONDON"]
  }]
 },
 {
  "payrollCode": "3",
  "payAmount": 12.75,
  "basis": "Hourly",
  "payCode": "BASIC",
  "payAmountMultiplier": 37
 }
]

Conclusion

Whilst you can use a series of GET and PUTs to update payment amounts on a payrun, it can be a lot easier to use the ImportPay method.

It overwrites any existing payment information, so the only time it wouldn’t be appropriate is if you wanted to keep the existing values that are known in Staffology but not in your own systems.

Duane Jackson, December 19th, 2019

---

---