Make a payroll export
Makes a payroll file from a timesheet period's approved, locked timesheets, for the whole organisation or chosen
sites. People not in an earlier file for the period get their first lines; people whose figures changed since one
(a timesheet reopened and approved again, or a leaver's annual leave balance) get the difference as correction
lines; people with nothing new aren't repeated. Hours are by pay code and net of unpaid breaks; days by pay code.
Returns invalid_state while a type of leave in it has no pay code or two pay codes clash, while the period is
running, and when nothing is new. The file is kept: download it from
/payroll-exports/{payroll_export_id}/file. payroll_export.created fires.
Scope: attendance:payroll · Plan: Pro and Enterprise, with the payroll export; in test mode too, the payroll export needs Pro.
AuthorizationBearer <token>Send Authorization: Bearer <token> on every request. The token is one of:
| Prefix | What it is | Where it may be used |
|---|---|---|
agoo_sk_live_ | Secret key, live mode | Your servers only |
agoo_sk_test_ | Secret key, test mode | Your servers only |
agoo_pk_live_ | Publishable key, live mode | Browsers and apps: create pre-registrations and bookings, read public booking types (with their intake questions) and their free slots, read the visit types open for pre-registration with their public forms. Never lists people. |
agoo_pk_test_ | Publishable key, test mode | As above, in test mode |
Admins create keys in Console → Developers → API keys and choose each key's scopes. A key is shown once. Never put a secret key in a URL, a browser or a mobile app.
Scope: attendance:payroll
Idempotency-Key*stringA UUID you generate for this operation. If you retry with the same key within 24 hours, Agoo returns the
original response instead of acting twice. While the first request is still running, a retry returns
conflict. Reusing a key with a different request returns idempotency_key_reused. Responses with
rate_limited, internal_error or unavailable aren't stored, so retry those with the same key.
uuidapplication/json- body
period_id*TimesheetPeriodIdA timesheet period ID (TypeID with the tsp prefix).
^tsp_[0-7][0-9a-hjkmnp-tv-z]{25}$"tsp_01m5a2b3c4d5e6f7g8h9jkmnpr"site_ids?array<>Only people who work at these sites; the whole organisation when left out.
items <= 200format?stringxlsx also has the other layout, each day's figures and breaks, and notes.
"csv""csv""xlsx"layout?string"long""long""wide"note?stringA note kept with the file.
length <= 300The payroll export, with its file made and kept.
application/json- response
A payroll file made from a timesheet period's approved, locked timesheets. Never changed once made: later changes go in a later file as corrections.
id*PayrollExportIdA payroll export ID (TypeID with the payroll_export prefix).
^payroll_export_[0-7][0-9a-hjkmnp-tv-z]{25}$"payroll_export_01m5c4d5e6f7g8h9jkmnpqrstv"number*integerYour organisation's payroll exports are numbered 1, 2, 3…
3period*site_ids*array<>|The sites it was made for; null for the whole organisation.
format*string"csv""xlsx"layout*stringlong: a row per person and pay code. wide: a row per person, a column per pay code. custom: one of your organisation's own layouts, made in the Console.
"long""wide""custom"people*integerPeople in it.
corrections*integerPeople whose lines correct an earlier file for the same period.
lines*integersuperseded*integerPeople in it whose figures a later file corrected.
file*created_by*|Who made it; null when an integration did.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$created_via*string"person""api"created_at*stringdate-timecurl -X POST 'https://api.agoo.ardent.africa/v1/payroll-exports' \ -H 'Idempotency-Key: 3f6b2a1e-8c4d-4f7a-9b2e-5d1c0a7e9f64' \ -H 'Content-Type: application/json' \ -d '{ "period_id": "tsp_01m5a2b3c4d5e6f7g8h9jkmnpr", "format": "csv", "layout": "long"}'{ "id": "payroll_export_01m5c4d5e6f7g8h9jkmnpqrstv", "number": 3, "period": { "id": "tsp_01m5a2b3c4d5e6f7g8h9jkmnpr", "starts_on": "2019-08-24", "ends_on": "2019-08-24", "payroll_on": "2019-08-24" }, "site_ids": [ "site_01kjpt3yw0fz0v414608h9x65s" ], "format": "csv", "layout": "long", "people": 0, "corrections": 0, "lines": 0, "superseded": 0, "file": { "name": "ridge-hospital-payroll-september-2026-3.csv", "content_type": "string", "byte_size": 0, "sha256": "string" }, "created_by": "string", "created_via": "person", "created_at": "2019-08-24T14:15:22Z"}List payroll exports GET
Returns your organisation's payroll files, newest first: each one's period, sites, format and layout, how many people and lines it holds, how many of those people are corrections of an earlier file, how many a later file corrected, and its file's name, size and SHA-256. Filter by `period_id`. **Scope:** `attendance:payroll` · **Plan:** Pro and Enterprise, with the payroll export; in test mode too, the payroll export needs Pro.
Get a payroll export GET
Returns one payroll export. **Scope:** `attendance:payroll` · **Plan:** Pro and Enterprise, with the payroll export; in test mode too, the payroll export needs Pro.