ReferenceHR API

People

The directory, one person's record, new starters, removing people, and emergency contacts.

Method	Path	Summary
GET	`/api/me`	Who you are: the signed-in person and what they can do here
GET	`/api/people`	The directory
GET	`/api/people/:id`	Get a person's HR record
PATCH	`/api/people/:id`	Update a person's HR record
POST	`/api/people`	New starter (before their account exists) — HR admins only
DELETE	`/api/people/:id`	Remove someone from HR (a mistake, a duplicate, a service account)
POST	`/api/people/:id/contacts`	Add an emergency contact
PUT	`/api/people/:id/contacts/:cid`	Update an emergency contact
DELETE	`/api/people/:id/contacts/:cid`	Remove an emergency contact
GET	`/api/activity`	Recent HR activity

#Who you are: the signed-in person and what they can do here

GET/api/me

Address: https://<your-org>.brambleit.cloud/hr/api/me
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Response 200

Field	Type	Description
`user`	object
`user.id`	integer
`user.name`	string
`user.first_name`	string
`user.email`	string
`me`	any
`is_admin`	boolean
`is_manager`	boolean
`team_size`	integer
`settings`	object
`settings.year_start_month`	any
`settings.bank_holidays`	array of any
`settings.region`	any
`settings.region_name`	string
`settings.half_days`	boolean
`settings.show_leave_types`	boolean
`settings.default_allowance`	any
`settings.carry_over_max`	any
`settings.overlap_mode`	any
`leave_types`	array of any
`counts`	object
`counts.approvals`	integer
`counts.tasks`	integer
`counts.to_ack`	any
`today`	any

Example response

JSON

{
  "user": {
    "id": 42,
    "name": "Example name",
    "first_name": "Alex",
    "email": "alex@example.com"
  },
  "me": null,
  "is_admin": true,
  "is_manager": true,
  "team_size": 1,
  "settings": {
    "year_start_month": null,
    "bank_holidays": [],
    "region": null,
    "region_name": "Example region name",
    "half_days": false,
    "show_leave_types": false,
    "default_allowance": null,
    "carry_over_max": null,
    "overlap_mode": null
  },
  "leave_types": [],
  "counts": {
    "approvals": 1,
    "tasks": 1,
    "to_ack": null
  },
  "today": null
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/me', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#The directory

GET/api/people

Address: https://<your-org>.brambleit.cloud/hr/api/people
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Response 200

Field	Type	Description
`people`	array of any

Example response

JSON

{
  "people": []
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/people', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Get a person's HR record

GET/api/people/:id

What you see depends on who you are — HR admins see everything, managers see their reports' work details, everyone sees the directory card.

Address: https://<your-org>.brambleit.cloud/hr/api/people/:id
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/people/42', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Update a person's HR record

PATCH/api/people/:id

Send only the fields to change. People can change their own preferred_name, pronouns, personal_email, personal_phone, work_phone, date_of_birth, address, ni_number and bio. HR admins can also change first_name, last_name, work_email, job_title, department, location, manager_id, employee_number, start_date, end_date, leaving_reason, probation_end, employment_type, contract_type, work_days, hours_per_week and hr_notes. Allowances change through POST /api/leave/allowance-changes.

Address: https://<your-org>.brambleit.cloud/hr/api/people/:id
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`k`	any

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
400	That … isn't valid
400	Someone can't report to themselves or to someone who reports to them
400	The last day is before their start date
403	You can't change this person's details
403	Only HR can change …

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/people/42', {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"k":"…"}),
});
const data = await res.json();

#New starter (before their account exists) — HR admins only

POST/api/people

Address: https://<your-org>.brambleit.cloud/hr/api/people
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Request body JSON

Name	Type	Description
`first_name`	string
`last_name`	string
`work_email`	string
`manager_id`	number
`personal_email`	string
`job_title`	string
`department`	string
`location`	string
`start_date`	string (date)
`employment_type`	string
`contract_type`	string
`work_days`	integer

Response 201

Field	Type	Description
`id`	integer

Example response

JSON

{
  "id": 42
}

Errors

Status	Message
400	Give their first and last name
400	Someone already has that work email
403	Only HR admins can add people

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/people', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"first_name":"Alex","last_name":"Morgan","work_email":"alex@example.com","manager_id":12.5,"personal_email":"alex@example.com","job_title":"Example job title","department":"string","location":"string","start_date":"2026-11-12","employment_type":"string","contract_type":"string","work_days":1}),
});
const data = await res.json();

#Remove someone from HR (a mistake, a duplicate, a service account)

DELETE/api/people/:id

Remove someone from HR (a mistake, a duplicate, a service account). Their account isn't touched and the sync won't add them back; BRM-Admin → HR can. Leavers should get a last day instead, which keeps them listed.

Address: https://<your-org>.brambleit.cloud/hr/api/people/:id
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
400	You can't remove yourself from HR
403	Only HR admins can remove people

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/people/42', {
  method: 'DELETE',
  credentials: 'include',
});
const data = await res.json();

#Add an emergency contact

POST/api/people/:id/contacts

Address: https://<your-org>.brambleit.cloud/hr/api/people/:id/contacts
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`name`	string
`phone`required	string
`email`required	string
`relationship`	string

Response 201

Field	Type	Description
`id`	integer

Example response

JSON

{
  "id": 42
}

Errors

Status	Message
400	Give their name
400	Give a phone number or email

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/people/42/contacts', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"name":"Example name","phone":"string","email":"alex@example.com","relationship":"string"}),
});
const data = await res.json();

#Update an emergency contact

PUT/api/people/:id/contacts/:cid

Address: https://<your-org>.brambleit.cloud/hr/api/people/:id/contacts/:cid
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Path parameters

Name	Type	Description
`id`required	integer
`cid`required	number

Request body JSON

Name	Type	Description
`name`	string
`relationship`	string
`phone`	string
`email`	string

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
400	Give their name

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/people/42/contacts/12.5', {
  method: 'PUT',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"name":"Example name","relationship":"string","phone":"string","email":"alex@example.com"}),
});
const data = await res.json();

#Remove an emergency contact

DELETE/api/people/:id/contacts/:cid

Address: https://<your-org>.brambleit.cloud/hr/api/people/:id/contacts/:cid
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Path parameters

Name	Type	Description
`id`required	integer
`cid`required	number

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/people/42/contacts/12.5', {
  method: 'DELETE',
  credentials: 'include',
});
const data = await res.json();

#Recent HR activity

GET/api/activity

Address: https://<your-org>.brambleit.cloud/hr/api/activity
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: HR.

Response 200

Field	Type	Description
`activity`	array of object
`activity[].employee_id`	any
`activity[].actor_name`	any
`activity[].action`	string
`activity[].detail`	string, or null
`activity[].created_at`	string (date-time)

Example response

JSON

{
  "activity": [
    {
      "employee_id": null,
      "actor_name": null,
      "action": "string",
      "detail": "string",
      "created_at": "2026-11-12T09:30:00.000Z"
    }
  ]
}

Errors

Status	Message
403	HR admins only

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/activity', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

Was this page helpful?