Update a person's HR profile
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_daysis for a notice longer than the one the Labour Act gives (s.17); leave itnullfor the Act's.digital_addressmust be a GhanaPost GPS address, such asGA-123-4567.marital_statusis accepted only when your organisation records it, and it anddisability_declaredare kept but never returned through the API.
Scope: hr:write · 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:write
person_id*stringThe person's ID.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"application/json- body
The fields to change. Send null to clear one. Marital status and a self-declared disability are kept in Agoo only: they're neither read nor changed through the API.
legal_name?|As on their Ghana Card.
length <= 160date_of_birth?|dategender?|"female""male""not_stated"nullnationality?|ISO 3166 country code.
^[A-Za-z]{2}$personal_email?|emaillength <= 254personal_phone?|^\+[1-9][0-9]{7,14}$home_address?|length <= 300digital_address?|A GhanaPost GPS address, such as GA-123-4567.
length <= 20languages?array<string>|items <= 10contract_type?|nullcontract_ends_on?|dateprobation_ends_on?|datenotice_days?|A notice longer than the one the Labour Act gives (s.17). null: the Act's.
1 <= value <= 366work_pattern?|"weekdays""six_day""seven_day""shifts""flexible"nullcost_centre?|length <= 60continuous_service_from?|dategrade?|length <= 60tier2_trustee?|length <= 120tier2_scheme?|length <= 120tier3_scheme?|length <= 120tier3_percent?|0 <= value <= 16.5The updated 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 PATCH 'https://api.agoohq.com/v1/people/person_01kjsesxm0e4zbyvkr7bcfxbfg/hr-profile' \ -H 'Content-Type: application/json' \ -d '{ "home_address": "Flat 4, Kanda Estates, Accra", "digital_address": "GA-123-4567", "tier3_percent": 7.5}'{ "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": "Flat 4, Kanda Estates, 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": 7.5, "statutory_ids": [ { "kind": "ghana_card", "last4": "6780", "expires_on": "2031-03-01" }, { "kind": "ssnit", "last4": "3307", "expires_on": null } ], "updated_at": "2026-10-19T11:05:00Z"}Get a person's HR profile GET
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 `null`s and an `open_ended` contract. **Scope:** `hr:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
List a person's employment history GET
Returns every change to the person's job title, department, position, manager, sites, employment type, contract, contracted hours and grade, and their start and leaving dates, newest first by the day each took effect, a page at a time. Each line says what it was and what it became, in words, with the IDs of a department, position, manager or sites. **Scope:** `hr:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.