ReferenceHR API

Time off

Balances, requests and approvals, previews (how many days a request would use), the team calendar, adjustments, and dated allowance changes.

Method	Path	Summary
GET	`/api/leave/balance`	A person's time-off balance
GET	`/api/leave/requests`	List time-off requests
POST	`/api/leave/preview`	How many days a request would use
POST	`/api/leave/requests`	Request time off
POST	`/api/leave/requests/:id/decide`	Approve or decline time off
POST	`/api/leave/requests/:id/cancel`	Cancel time off
POST	`/api/leave/adjustments`	Add or take away days
DELETE	`/api/leave/adjustments/:id`	Remove an adjustment
POST	`/api/leave/allowance-changes`	From a leave year on, someone's allowance is `days` a year ('set') or `days` on top of the policy ('extra')
DELETE	`/api/leave/allowance-changes/:id`	Remove an allowance change
GET	`/api/leave/calendar`	Who's off when
GET	`/api/leave/types`	Leave types

#A person's time-off balance

GET/api/leave/balance

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

Query parameters

Name	Type	Description
`employee`	any	The person (default you).
`date`	string (date)	The leave year containing this date (default today).

Response 200

Field	Type	Description
`balance`	any

Example response

JSON

{
  "balance": null
}

Errors

Status	Message
403	You can't see this person's time off

Example request

JavaScript

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

#List time-off requests

GET/api/leave/requests

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

Query parameters

Name	Type	Description
`scope`	any	`mine` (default), `approvals` (waiting for you to decide), or a person's with `employee`.
`employee`	any	The person.

Response 200

Field	Type	Description
`requests`	array of any

Example response

JSON

{
  "requests": []
}

Errors

Status	Message
403	You can't see this person's time off

Example request

JavaScript

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

#How many days a request would use

POST/api/leave/preview

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

Request body JSON

Name	Type	Description
`employee_id`	integer
`type_id`	integer

Response 200

Errors

Status	Message
400	Choose the type of time off
403	You can't book time off for this person

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/leave/preview', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"employee_id":7,"type_id":7}),
});
const data = await res.json();

#Request time off

POST/api/leave/requests

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

Request body JSON

Name	Type	Description
`employee_id`	integer	Who it's for (default you; HR and managers can book for others).
`type_id`	integer	The leave type.
`note`	string	A note for the approver.
`start_date`	any	First day.
`end_date`	any	Last day.

Response 201

Field	Type	Description
`id`	integer
`status`	string
`days`	array of any

Example response

JSON

{
  "id": 42,
  "status": "active",
  "days": []
}

Errors

Status	Message
400	Choose the type of time off
400	That's before their start date
400	That's after their last day
403	You can't book time off for this person

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/leave/requests', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"employee_id":7,"type_id":7,"note":"string","start_date":"…","end_date":"…"}),
});
const data = await res.json();

#Approve or decline time off

POST/api/leave/requests/:id/decide

Address: https://<your-org>.brambleit.cloud/hr/api/leave/requests/:id/decide
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
`approve`	any	`true` to approve, `false` to decline.
`note`	any	A note for the person.
`override`	any	Approve even though it goes over their balance.

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
400	This request has already been …
403	You can't approve this person's time off
409	Approving this would take … to … days in …. Approve anyway?
409	That takes … to … days of … this year — the limit is …. Approve anyway?
409	Someone else has just dealt with this request

Example request

JavaScript

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

#Cancel time off

POST/api/leave/requests/:id/cancel

Address: https://<your-org>.brambleit.cloud/hr/api/leave/requests/:id/cancel
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	This request is already …
400	This has already started — ask your manager to change it
403	You can't cancel this person's time off

Example request

JavaScript

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

#Add or take away days

POST/api/leave/adjustments

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

Request body JSON

Name	Type	Description
`employee_id`	integer	The person.
`days`	number	Days to add (negative to take away).
`reason`	string	Why.
`date`	string (date)	Which leave year it counts in.

Response 201

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
400	Give a number of days (use a minus for fewer)
400	Give a reason — it shows on their balance
403	Only HR admins can adjust allowances

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/leave/adjustments', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"employee_id":7,"days":12.5,"reason":"string","date":"2026-11-12"}),
});
const data = await res.json();

#Remove an adjustment

DELETE/api/leave/adjustments/:id

Address: https://<your-org>.brambleit.cloud/hr/api/leave/adjustments/: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	number

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
403	Only HR admins can adjust allowances
404	Adjustment not found

Example request

JavaScript

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

#From a leave year on, someone's allowance is `days` a year ('set') or `days` on top of the policy ('extra')

POST/api/leave/allowance-changes

From a leave year on, someone's allowance is days a year ('set') or days on top of the policy ('extra'). One change per person per year: saving another for the same year replaces it.

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

Request body JSON

Name	Type	Description
`employee_id`	integer
`kind`	string
`days`required	number
`from`required	string (date)
`reason`	string

Response 201

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
400	Give a number of days
400	The allowance must be between 0 and 366 days
400	Extra days must be between -100 and 100
400	Choose the leave year it starts from
403	Only HR admins can change allowances

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/leave/allowance-changes', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"employee_id":7,"kind":"string","days":12.5,"from":"2026-11-12","reason":"string"}),
});
const data = await res.json();

#Remove an allowance change

DELETE/api/leave/allowance-changes/:id

Address: https://<your-org>.brambleit.cloud/hr/api/leave/allowance-changes/: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	number

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
403	Only HR admins can change allowances
404	Allowance change not found

Example request

JavaScript

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

#Who's off when

GET/api/leave/calendar

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

Query parameters

Name	Type	Description
`from`	string (date)	First date.
`to`	string (date)	Last date.

Response 200

Field	Type	Description
`from`	any
`to`	any
`days`	array of any
`entries`	array of any
`people`	array of any

Example response

JSON

{
  "from": null,
  "to": null,
  "days": [],
  "entries": [],
  "people": []
}

Example request

JavaScript

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

#Leave types

GET/api/leave/types

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

Response 200

Field	Type	Description
`types`	array of any

Example response

JSON

{
  "types": []
}

Example request

JavaScript

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

Was this page helpful?