Get a person's HR profile
Returns the person's personal and employment details, their pension schemes and their statutory numbers by
kind and last four only. Full statutory numbers, pay accounts and emergency contacts, next of kin and
beneficiaries are never in the API. Someone with no HR details recorded yet comes back with nulls and an
open_ended contract.
Scope: hr:read · Plan: Pro and Enterprise in live mode; every plan in test mode.
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: hr:read
person_id*stringThe person's ID.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"The person's HR profile.
application/json- response
A person's HR record as the API shows it: personal and employment details, pension schemes, and statutory numbers by kind and last four only. Full statutory numbers, pay accounts, emergency contacts, next of kin, beneficiaries, marital status and disability never leave Agoo through the API.
object*"hr_profile""hr_profile"person_id*PersonIdA person ID (TypeID with the person prefix).
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"legal_name*|As on their Ghana Card.
"Nii Armah Quartey"date_of_birth*|dategender*|not_stated: they prefer not to say.
"female""male""not_stated"nullnationality*|ISO 3166 country code.
"GH"personal_email*|"nii.armah@mail.example"personal_phone*|E.164 phone number.
"+233241234567"home_address*string|nulldigital_address*|A GhanaPost GPS address.
"GA-123-4567"languages*array<string>The languages they speak.
[ "English", "Ga", "Twi"]contract_type*ContractTypeopen_ended, fixed_term, casual, apprenticeship, national_service or internship.
"open_ended""fixed_term""casual""apprenticeship""national_service""internship"contract_ends_on*|When a fixed-term contract ends.
dateprobation_ends_on*|datenotice_days*|A notice in days longer than the one the Labour Act gives (s.17). null: the Act's.
work_pattern*|weekdays (Monday to Friday), six_day, seven_day, shifts or flexible.
cost_centre*string|nullcontinuous_service_from*|When their continuous service began, if not on started_on.
dategrade*string|nullposition_id*|The position they hold now. null: none.
tier2_trustee*|The trustee of their Tier 2 occupational pension scheme.
tier2_scheme*|Their Tier 2 scheme.
tier3_scheme*|Their Tier 3 provident fund or personal pension scheme.
tier3_percent*|Their Tier 3 contribution, as a percentage of pay.
statutory_ids*array<>Their statutory and identity numbers by kind and last four only: full numbers never leave Agoo through the API.
updated_at*stringdate-timecurl -X GET 'https://api.agoohq.com/v1/people/person_01kjsesxm0e4zbyvkr7bcfxbfg/hr-profile'{ "object": "hr_profile", "person_id": "person_01kjw4mg80efgb5aqbsqnxhtbh", "legal_name": "Nii Armah Quartey", "date_of_birth": "1994-05-12", "gender": "male", "nationality": "GH", "personal_email": "nii.armah@mail.example", "personal_phone": "+233241234567", "home_address": "House 12, Abelemkpe Road, Accra", "digital_address": "GA-123-4567", "languages": [ "English", "Ga", "Twi" ], "contract_type": "open_ended", "contract_ends_on": null, "probation_ends_on": "2021-12-14", "notice_days": null, "work_pattern": "weekdays", "cost_centre": "CC-300", "continuous_service_from": "2021-06-14", "grade": "G5", "position_id": null, "tier2_trustee": "Ridge Pension Trustees", "tier2_scheme": "Volta Bank Staff Occupational Pension Scheme", "tier3_scheme": "Volta Bank Provident Fund", "tier3_percent": 5, "statutory_ids": [ { "kind": "ghana_card", "last4": "6780", "expires_on": "2031-03-01" }, { "kind": "ssnit", "last4": "3307", "expires_on": null } ], "updated_at": "2026-10-14T10:02:00Z"}Update a position PATCH
Changes a position's title, department, site, grade, the position it reports to, its full-time equivalent or whether it's budgeted, or freezes, closes or reopens it. Send only the fields you want to change; `null` clears an optional one. - A position someone holds can't be frozen or closed (`invalid_state`): change their job first. - `status: vacant` reopens a frozen or closed position; it shows `filled` while someone holds it. Who holds a position is changed by a job change, never here. - Fires `position.updated`, with `previous_attributes.changed` naming what changed. **Scope:** `hr:write` · **Plan:** Pro and Enterprise in live mode; Growth, Pro and Enterprise in test mode.
Update a person's HR profile PATCH
Changes the person's personal and employment details. Send only the fields you want to change; `null` clears one. - Job title, department, position, manager, sites, employment type and contracted hours change with a job change (`POST /people/{person_id}/job-changes`), so each has a date and a line of employment history. - `notice_days` is for a notice longer than the one the Labour Act gives (s.17); leave it `null` for the Act's. - `digital_address` must be a GhanaPost GPS address, such as `GA-123-4567`. - `marital_status` is accepted only when your organisation records it, and it and `disability_declared` are kept but never returned through the API. **Scope:** `hr:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.