The quick way to import pay via the API

Posted on Thursday, 19th Dec '19

Duane Jackson by Duane Jackson


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

Related Articles

A quick guide to calculating labour turnover

28th Feb '24

If your labour turnover rate is high, it’s a red flag that can indicate an unhappy workforce.  This means tracking your labour turnover rate can be essential to your business’ wellbeing.  But it doesn’t stop there. You need to understand the why behind your labour turnover rate; you must get effective feedback as well as […]

by Conrad Emmett

Pensions and Climate Change – How Employers Could be Impacted

15th Dec '22

Pension funds in the UK are in the trillions. With government regulations constantly updating to ensure this money is invested in the Paris Agreement-aligned green investment strategies, read more on how pensions and climate change are working together.

by Duane Jackson


Chat Now