HR and payroll

Agoo records when staff clock in and out, against their shifts and leave. These tools move that information to and from the systems your HR and payroll teams already use.

Import staff from CSVCopy Anchor Link

Admins import people in Console → People → Import CSV, starting from its Download template. The main columns:

full_name,email,role,sites,phone,department,job_title,employee_id
Kwame Mensah,kwame.mensah@voltabank.example,Host,Ridge HQ,+233241234567,Treasury,Head of Treasury,VB-0142
Nii Armah,nii.armah@voltabank.example,Employee,Tema Branch,0205550142,Operations,Operations Officer,VB-0377

Save the file as UTF-8 CSV so names with accents or other characters survive. The import shows a preview of what will be created and updated before anything changes. Every column, including attendance, start dates, employment type and contracted hours, is in Invite your team. The planned CLI's agoo people import will take the same file.

Set employee_id for everyone who appears on payroll. It's how your payroll team will match Agoo's export to their records, where it's the employee number.

Export timesheets for payrollCopy Anchor Link

On Pro and Enterprise, HR, Owners and Admins make payroll files in Attendance → Payroll in the Console. A file covers one timesheet period, for the whole organisation or chosen sites, and holds only approved, locked timesheets; Agoo lists who isn't in it and why. Choose CSV, or Excel (.xlsx), and a layout: long, wide or one of your own. The guide Export for payroll walks through it. Your own systems can make and download the same files with the API.

Pay codesCopy Anchor Link

Every line in a payroll file has a pay code. Each organisation names its own and sets each one's multiplier, starting from these defaults:

Multipliers run from 0 to 10, to two decimal places, or are empty when payroll sets the rate. A kind of time can be left out of payroll files altogether. Agoo refuses to make a file while any time in it has no code, or while one code covers things paid differently (hours and days, or different multipliers), and says which: nothing goes out as regular hours by default. Every kind of leave appears under its own code, private kinds such as sick and maternity leave included, which is why payroll files have their own scope.

Long layoutCopy Anchor Link

One row per person and pay code. The Pay codes sheet in Excel.

Wide layoutCopy Anchor Link

One row per person: employee_number, name, department, site, period_start, period_end, correction, a column for each pay code in the file (empty when the person has none of it), then approved_by, approved_at and export_id. The By person sheet in Excel.

Excel sheetsCopy Anchor Link

An Excel file starts with the layout you chose, then has Pay codes (long), By person (wide), Days (each person's days: status, first in and last out, worked, regular, daily and weekly overtime, rest-day, holiday and night hours, extra time and its decision, paid, unpaid and nursing break minutes and where the unpaid break came from, minutes late and left early, leave and its code, and the holiday) and Notes (who made it and when, the period and payroll date, the sites, approvals, reopenings and their reasons, corrections and which file each corrects, who isn't in the file and why, kinds of time left out, people with no employee number, and how to read the units).

Your own layoutCopy Anchor Link

If your payroll system imports its own columns, build a layout once in the Console: one row per pay code or per person; the columns, in your order, with your own headings (employee number, name, email, department, job title, site, employment type, pay code, category, units, unit, multiplier, a column per pay code, period start, period end, period, payroll date, correction, approved by, approved at, export, or fixed text); the separator (comma, semicolon, tab or pipe); the date format (YYYY-MM-DD, DD/MM/YYYY or MM/DD/YYYY); hours as decimals (7.50) or hours and minutes (7:30); a header row or none; and a file name pattern from {org}, {period}, {starts}, {ends}, {export} and {layout}. An organisation can keep up to 20. CSV files in your own layout have Windows line endings and no byte-order mark. Ready-made layouts for payroll systems used in Ghana are planned, each made from that system's real import file.

CorrectionsCopy Anchor Link

A file is never changed once made. If a person's figures for a period change afterwards (their timesheet reopened and approved again, or a leaver's balance moved), the next file for that period carries correction lines for them: the difference, marked correction, dated to the original period, and the earlier file is marked superseded for them. A second file for a period carries only what's new or changed. Kinds of time left out are left out of corrections too.

Before you send it to payrollCopy Anchor Link

• Read the Notes sheet, or the file's details in the Console: who isn't in the file and why, and who has no employee number.
• Hours are decimal. 7.50 is seven and a half hours, already net of unpaid breaks. Choose hours and minutes in your own layout if your payroll expects 7:30.
• Check the checksum if you pass files on: every file is kept with its SHA-256, and downloading it again gives the same bytes.
• Ghana public holidays are applied automatically: PHW for work on them, PH for the paid day off.

Read attendance with the APICopy Anchor Link

For a custom integration, for example a nightly job that loads attendance into your payroll database, use the API on Pro and Enterprise:

Webhooks tell you as things happen: attendance.clocked_in, attendance.clocked_out, attendance.late, and attendance.voided when a punch stops counting; leave.requested, leave.approved, leave.declined and leave.cancelled for leave; timesheet.submitted, timesheet.approved and timesheet.reopened for timesheets; payroll_export.created when a payroll file is made, in the Console or through the API. Pay from timesheet.approved: an approved timesheet is locked, so its totals don't change unless it's reopened, which fires timesheet.reopened and later a new timesheet.approved. roster.published tells you a site's roster changed, and shift_swap.approved and shift_claim.approved that a shift moved to someone else, so your payroll or workforce system can follow the roster. Private kinds of leave, such as sick leave, come as away, never with what they are, except in payroll files, which name every kind by its pay code and so need their own scope, attendance:payroll. Punches a manager added or corrected in the Console have the method manual, with who added them and why; a corrected time voids the wrong punch and adds the right one, so drop voided punches from your records. To pay from Agoo's own files, wait for a period's timesheets to be approved, then POST /payroll-exports with an Idempotency-Key and download its file; make another for the same period after a timesheet.reopened and its new timesheet.approved, and it carries only the corrections. The API makes files in the long and wide layouts; your own layouts and the pay codes are set in the Console. The payroll export itself is Pro's and Enterprise's, so these calls return plan_required for an organisation on another plan, in test mode too. The recipe attendance to payroll is a complete example. Fields are described in the API reference.

HR and payroll syncCopy Anchor Link

HR and payroll sync is planned. On Enterprise, our team will set up an ongoing sync with your HR or payroll system, so that joiners, leavers and department changes flow into Agoo, and attendance flows back, without anyone exporting files. What's possible will depend on your system and how it can be reached; talk to us about yours.

If your organisation uses Microsoft Entra ID or another SCIM-capable directory as its source of truth for staff, SCIM provisioning on Pro, also planned, will give you the people half of this.

PrivacyCopy Anchor Link

Attendance records are personal data under the Data Protection Act, 2012 (Act 843). Payroll files include only the columns above: no face templates, photos or locations. They name every kind of leave, private kinds included, so only HR, Owners and Admins, and integrations with attendance:payroll, can make or download them; someone whose role covers some sites only makes and sees files for those sites. Making a file, and every download, is recorded in the audit trail. Agoo keeps each file with your attendance records; keep the copies you download only as long as payroll needs them.

RelatedCopy Anchor Link