Get a department
Returns one department, archived or not.
Scope: people: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: people:read
department_id*stringThe department's ID.
^dept_[0-7][0-9a-hjkmnp-tv-z]{25}$"dept_01kjsd2v80e5q7m3c9x4ht6wfa"The department.
application/json- response
One of your organisation's departments. A person's department is the name of their department.
id*DepartmentIdA department ID (TypeID with the dept prefix).
^dept_[0-7][0-9a-hjkmnp-tv-z]{25}$"dept_01kjsd2v80e5q7m3c9x4ht6wfa"object*"department""department"name*stringUnique among the departments that aren't archived.
1 <= length <= 120"Treasury"code*|Your own short code for it.
length <= 20"TRY"parent_id*|The department it sits under. null: at the top.
head_id*|The person who heads it. null: no one is named.
cost_centre*|length <= 60"CC-210"archived*booleantrue for a department that's archived: kept, with its history, but not offered for new people.
people*integerHow many active people are in it.
0 <= valuecreated_at*stringdate-timeupdated_at*stringdate-timecurl -X GET 'https://api.agoohq.com/v1/departments/dept_01kjsd2v80e5q7m3c9x4ht6wfa'{ "id": "dept_01kjsd2v80e5q7m3c9x4ht6wfa", "object": "department", "name": "Treasury", "code": "TRY", "parent_id": "dept_01kjsd1qg0f2n8r5bz7ke3yc4d", "head_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg", "cost_centre": "CC-210", "archived": false, "people": 14, "created_at": "2026-03-03T09:00:00Z", "updated_at": "2026-10-06T14:30:00Z"}Create a department POST
Makes a department. Names are unique among the departments that aren't archived: a name already in use returns `conflict`. A `parent_id` must be one of your departments that isn't archived, and `head_id` someone in your directory. - Fires `department.created`. **Scope:** `hr:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
Update a department PATCH
Changes a department. Send only the fields you want to change; `null` clears an optional one. - Renaming a department renames it for everyone in it: their `department` changes with it. - `archived: true` archives a department nobody active is in, with no departments under it and no positions that aren't closed; otherwise it returns `invalid_state`. `archived: false` brings one back, unless another department now has its name (`conflict`). Its history stays either way. - Fires `department.updated`, with `previous_attributes.changed` naming what changed. **Scope:** `hr:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.