Docs
API referencePeople and H R

Update a department

Preview· P9
PATCH
/departments/{department_id}

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.

Authorization

headerAuthorizationBearer <token>

Send Authorization: Bearer <token> on every request. The token is one of:

PrefixWhat it isWhere it may be used
agoo_sk_live_Secret key, live modeYour servers only
agoo_sk_test_Secret key, test modeYour servers only
agoo_pk_live_Publishable key, live modeBrowsers 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 modeAs 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

Path Parameters

department_id*string

The department's ID.

Match^dept_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"dept_01kjsd2v80e5q7m3c9x4ht6wfa"

Request Body

application/json
  1. body

The fields to change. Send null to clear an optional field.

name?string

Its people's department changes with it.

Length1 <= length <= 120
code?|
Lengthlength <= 20
parent_id?|

The department it sits under, never itself or one under it. null: at the top.

head_id?|null
cost_centre?|
Lengthlength <= 60
archived?boolean

true archives a department nobody active is in; false brings an archived one back.

Response Body

The updated department.

application/json
  1. response

One of your organisation's departments. A person's department is the name of their department.

id*DepartmentId

A department ID (TypeID with the dept prefix).

Match^dept_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"dept_01kjsd2v80e5q7m3c9x4ht6wfa"
object*"department"
Value in"department"
name*string

Unique among the departments that aren't archived.

Length1 <= length <= 120
Example"Treasury"
code*|

Your own short code for it.

Lengthlength <= 20
Example"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*|
Lengthlength <= 60
Example"CC-210"
archived*boolean

true for a department that's archived: kept, with its history, but not offered for new people.

people*integer

How many active people are in it.

Range0 <= value
created_at*string
Formatdate-time
updated_at*string
Formatdate-time
curl -X PATCH 'https://api.agoohq.com/v1/departments/dept_01kjsd2v80e5q7m3c9x4ht6wfa' \  -H 'Content-Type: application/json' \  -d '{  "head_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg",  "cost_centre": "CC-215"}'
{  "id": "dept_01kjsd2v80e5q7m3c9x4ht6wfa",  "object": "department",  "name": "Treasury",  "code": "TRY",  "parent_id": "dept_01kjsd1qg0f2n8r5bz7ke3yc4d",  "head_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg",  "cost_centre": "CC-215",  "archived": false,  "people": 14,  "created_at": "2026-03-03T09:00:00Z",  "updated_at": "2026-10-19T10:15:00Z"}

Get a department GET

Returns one department, archived or not. **Scope:** `people:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.

List positions GET

Returns your organisation's positions by title, each with who holds it now. Filter by department, or by status: `vacant` lists your vacancies. **Scope:** `people:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.