Section
INFO
Every response arrives in the shared envelope — code, message, messages, status_code, time — with the payload in data. The tables below describe what is inside data.
GET /section/get-by-id/{id}
Get section using its _id
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes |
Request body
No request body.
Response
| Field | Type | Description |
|---|---|---|
name | string | |
created_at | string | |
updated_at | string | |
is_deleted | boolean | |
parent_id | string |
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": {
"name": "string",
"created_at": "string",
"updated_at": "string",
"is_deleted": false,
"parent_id": "string"
},
"time": "2025-05-01T12:00:00Z"
}POST /section/get-paging
Get sections by paging
Request body
| Field | Type | Required | Description |
|---|---|---|---|
page | number | Yes | Default: 1 |
limit | number | Yes | Default: 20 |
search | string | No | |
parent_id | string | No | |
organization_id | string | No | |
top | boolean | No | Default: false |
updated_at | string (date-time) | No |
{
"page": 1,
"limit": 20,
"search": "string",
"parent_id": "63f8b0c4e4b0d3a2f8e4b0c4",
"organization_id": "63f8b0c4e4b0d3a2f8e4b0c4",
"top": false,
"updated_at": "2024-07-20T10:30:00Z"
}Response
data.total is the total number of records and data.data[] holds the current page. The table below describes one record.
| Field | Type | Description |
|---|---|---|
name | string | |
created_at | string | |
updated_at | string | |
is_deleted | boolean | |
parent | object | |
parent._id | string | |
parent.is_deleted | boolean | |
parent.name | string | |
chief | object | |
chief._id | string | |
chief.full_name | string | |
chief.is_deleted | boolean |
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": {
"total": 0,
"data": [
{
"name": "string",
"created_at": "string",
"updated_at": "string",
"is_deleted": false,
"parent": {
"_id": "string",
"is_deleted": false,
"name": "string"
},
"chief": {
"_id": "string",
"full_name": "string",
"is_deleted": false
}
}
]
},
"time": "2025-05-01T12:00:00Z"
}POST /section/create
Create a section (HR department). name and organizations (at least one entry) are required; parent_id nests the section under an existing one. Returns the created section with its parent expanded. Fails with 400 if a referenced organization, chief user or parent section does not exist.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Section name (required, 3-100 characters). |
organizations | object[] | Yes | Per-organization presence of the section (required, at least one). |
organizations[].organization_id | string | Yes | Organization the section exists in (required). Must exist. |
organizations[].is_available | boolean | Yes | Whether the section is active in this organization (required). A section whose every organization entry is is_available=false is auto soft-deleted by the backend. |
organizations[].chief_id | string | No | User who heads the section in this organization. Must reference an existing user. |
parent_id | string | No | Parent section, for a nested department tree. Must reference an existing section. Omit for a top-level section. |
{
"name": "Sales department",
"organizations": [
{
"organization_id": "63f8b0c4e4b0d3a2f8e4b0c4",
"is_available": false,
"chief_id": "63f8b0c4e4b0d3a2f8e4b0c4"
}
],
"parent_id": "63f8b0c4e4b0d3a2f8e4b0c4"
}Response
Same response shape as GET /section/get-by-id/{id}.
PUT /section/update/{id}
Update a section by ObjectId. name and organizations are both required — this is a full replacement of those fields, not a patch. The organizations named in the payload are pulled and re-pushed; organizations not named keep their existing entry. Returns the updated section with its parent expanded.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Section ObjectId to update |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Updated section name (required, 3-100 characters). |
organizations | object[] | Yes | Full replacement set of per-organization entries (required, at least one). The entries for the organizations named here are removed and re-added, so send every organization the section should remain active in — an organization left out keeps its previous entry. |
organizations[].organization_id | string | Yes | Organization the section exists in (required). Must exist. |
organizations[].is_available | boolean | Yes | Whether the section is active in this organization (required). A section whose every organization entry is is_available=false is auto soft-deleted by the backend. |
organizations[].chief_id | string | No | User who heads the section in this organization. Must reference an existing user. |
parent_id | string | No | Updated parent section. Must reference an existing section. |
{
"name": "Sales department",
"organizations": [
{
"organization_id": "63f8b0c4e4b0d3a2f8e4b0c4",
"is_available": false,
"chief_id": "63f8b0c4e4b0d3a2f8e4b0c4"
}
],
"parent_id": "63f8b0c4e4b0d3a2f8e4b0c4"
}Response
Same response shape as GET /section/get-by-id/{id}.
DELETE /section/delete/{id}
Soft-delete a section by ObjectId (sets is_deleted=true). Refuses with 400 when another section still names this one as its parent, or when any position still belongs to it — that error payload lists the blocking positions. Delete the child sections and re-home the positions first. Deleting an already-deleted section is a no-op.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Section ObjectId to delete |
Request body
No request body.
Response
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": "63f8b0c4e4b0d3a2f8e4b0c4",
"time": "2025-05-01T12:00:00Z"
}This page is generated from the OpenAPI spec.