ReferenceHR API

Documents

A person's documents (contracts, right-to-work…) and company documents people must acknowledge. Files are stored encrypted in Bramble.

Method	Path	Summary
GET	`/api/documents`	List documents
GET	`/api/documents/expiring`	HR: documents expiring in the next 60 days or already expired
POST	`/api/documents`	Upload a document
GET	`/api/documents/:id/file`	Download a document
PATCH	`/api/documents/:id`	Update a document's details
DELETE	`/api/documents/:id`	Delete a document
POST	`/api/documents/:id/ack`	Acknowledge a document
GET	`/api/documents/:id/acks`	HR: who has and hasn't acknowledged a company document

#List documents

GET/api/documents

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

Query parameters

Name	Type	Description
`employee`	number	A person's documents (leave out for company documents).

Response 200

Example request

JavaScript

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

#HR: documents expiring in the next 60 days or already expired

GET/api/documents/expiring

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

Response 200

Field	Type	Description
`documents`	array of object
`documents[].employee_name`	string

Example response

JSON

{
  "documents": [
    {
      "…d": "…",
      "employee_name": "Example employee name"
    }
  ]
}

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/documents/expiring', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Upload a document

POST/api/documents

multipart/form-data with the file and the fields below.

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

Request body

multipart/form-data with the file, plus these fields:

Name	Type	Description
`employee_id`	string	The person (leave out for a company document).
`category`	any	Its category.
`title`	string	Its title.
`visible_to_employee`	string	Let the person see it.
`requires_ack`	string	People must acknowledge they've read it.
`expires_on`	string (date)	When it expires (e.g. a visa).

Response 201

Field	Type	Description
`id`	integer

Example response

JSON

{
  "id": 42
}

Errors

Status	Message
400	Choose a file
403	Only HR admins can add company documents
403	You can't add documents for this person

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/documents', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"employee_id":"string","category":"…","title":"Example title","visible_to_employee":"string","requires_ack":"string","expires_on":"2026-11-12"}),
});
const data = await res.json();

#Download a document

GET/api/documents/:id/file

Address: https://<your-org>.brambleit.cloud/hr/api/documents/:id/file
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

Query parameters

Name	Type	Description
`download`	string

Example request

JavaScript

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

#Update a document's details

PATCH/api/documents/:id

Address: https://<your-org>.brambleit.cloud/hr/api/documents/: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
`title`	string
`category`	any
`visible_to_employee`	any
`requires_ack`	any
`expires_on`	string (date)

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
400	Give it a title
403	Only HR admins can change documents

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/hr/api/documents/42', {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"title":"Example title","category":"…","visible_to_employee":"…","requires_ack":"…","expires_on":"2026-11-12"}),
});
const data = await res.json();

#Delete a document

DELETE/api/documents/:id

Address: https://<your-org>.brambleit.cloud/hr/api/documents/: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
403	You can't delete this document

Example request

JavaScript

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

#Acknowledge a document

POST/api/documents/:id/ack

Address: https://<your-org>.brambleit.cloud/hr/api/documents/:id/ack
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 don't have an HR record yet
400	This document doesn't need acknowledging
403	This is not your document

Example request

JavaScript

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

#HR: who has and hasn't acknowledged a company document

GET/api/documents/:id/acks

Address: https://<your-org>.brambleit.cloud/hr/api/documents/:id/acks
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
`people`	array of any

Example response

JSON

{
  "people": []
}

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/documents/42/acks', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

Was this page helpful?