Departments — Proposed Guide

Departments: Departments organize employees and spending attribution. They may also provide accounting context, but department membership should not…

Overview

Departments organize employees and spending attribution. They may also provide accounting context, but department membership should not implicitly select a general-ledger account.

Key concepts

Maintain a stable department identifier, an optional parent and an active state. Preserve historical labels or effective dates for reporting.

Implementation considerations

Renaming or closing a department must not retroactively recode approved expenses. Cross-system department mapping requires an explicit external reference.

Proposed API behavior

GET /v1/departments is an illustrative design for this topic. Path and field names may change before implementation. Access would require an authorized organization context and operation-specific permission; no public API or authorization grant is available here.

Static example requests

# Proposed request text only; this reserved host is not a live API.
curl -X GET 'https://api.remizen.example/v1/departments?department_id=dept_example_123&status=draft' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Fictional response example

{
  "data": [
    {
      "organization_id": "org_example_123",
      "name": "Example business unit",
      "id": "departments_example_123"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Renaming or closing a department must not retroactively recode approved expenses. Cross-system department mapping requires an explicit external reference.

{
  "error": {
    "code": "validation_error",
    "message": "The proposed departments operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

Proposed data types

Related documentation