Position
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 /position/get-by-id/{id}
Get position using its _id
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes |
Request body
No request body.
Response
| Field | Type | Description |
|---|---|---|
_id | string | |
name | string | |
created_at | string | |
updated_at | string | |
is_deleted | boolean | |
completely_deleted | boolean | |
sections | object[] | |
sections[]._id | string | |
sections[].is_deleted | boolean | |
sections[].completely_deleted | boolean | |
sections[].name | string | |
organizations | object[] | |
organizations[]._id | string | |
organizations[].organization_id | string | |
organizations[].max_employee_count | number | |
organizations[].is_available | boolean |
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": {
"_id": "string",
"name": "string",
"created_at": "string",
"updated_at": "string",
"is_deleted": false,
"completely_deleted": false,
"sections": [
{
"_id": "string",
"is_deleted": false,
"completely_deleted": false,
"name": "string"
}
],
"organizations": [
{
"_id": "string",
"organization_id": "string",
"max_employee_count": 0,
"is_available": false
}
]
},
"time": "2025-05-01T12:00:00Z"
}POST /position/get-paging
Get positions by paging
Request body
| Field | Type | Required | Description |
|---|---|---|---|
page | number | Yes | Default: 1 |
limit | number | Yes | Default: 20 |
search | string | No | |
section_id | string | No | |
organization_id | string | No | |
accessed_organization_ids | string[] | No |
{
"page": 1,
"limit": 20,
"search": "string",
"section_id": "63f8b0c4e4b0d3a2f8e4b0c4",
"organization_id": "63f8b0c4e4b0d3a2f8e4b0c4",
"accessed_organization_ids": [
"63f8b0c4e4b0d3a2f8e4b0c4"
]
}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 |
|---|---|---|
_id | string | |
name | string | |
created_at | string | |
updated_at | string | |
max_employee_count | number | |
employee_count | number |
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": {
"total": 0,
"data": [
{
"_id": "string",
"name": "string",
"created_at": "string",
"updated_at": "string",
"max_employee_count": 0,
"employee_count": 0
}
]
},
"time": "2025-05-01T12:00:00Z"
}POST /position/create
Create an HR position. name, section_ids (at least one existing section) and organizations (at least one entry) are required. Returns the created position aggregated with its sections. Fails with 400 if the name already exists in the account, or if a referenced section or organization does not exist.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Position name (required, 3–100 characters). Must be unique within the account. |
section_ids | string[] | Yes | Sections (departments) this position belongs to (required, at least one). Every id must reference an existing, non-deleted section. |
organizations | object[] | Yes | Per-organization availability of the position (required, at least one). |
organizations[].organization_id | string | Yes | Organization the position is opened in (required). Must exist. |
organizations[].is_available | boolean | Yes | Whether the position is currently open for hiring in this organization (required). A position whose every organization entry is is_available=false is auto soft-deleted by the backend. |
organizations[].max_employee_count | number | No | Headcount cap for this organization. Defaults to 0 (uncapped) when omitted. |
{
"name": "Sales manager",
"section_ids": [
"63f8b0c4e4b0d3a2f8e4b0c4"
],
"organizations": [
{
"organization_id": "63f8b0c4e4b0d3a2f8e4b0c4",
"is_available": false,
"max_employee_count": 0
}
]
}Response
Same response shape as GET /position/get-by-id/{id}.
PUT /position/update/{id}
Update an HR position by ObjectId. name, section_ids and organizations are all 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 position aggregated with its sections.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Position ObjectId to update |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Updated position name (required, 3–100 characters). |
section_ids | string[] | Yes | Sections (departments) this position belongs to (required, at least one). Every id must reference an existing, non-deleted section. |
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 position should remain open in — an organization left out keeps its previous entry untouched. |
organizations[].organization_id | string | Yes | Organization the position is opened in (required). Must exist. |
organizations[].is_available | boolean | Yes | Whether the position is currently open for hiring in this organization (required). A position whose every organization entry is is_available=false is auto soft-deleted by the backend. |
organizations[].max_employee_count | number | No | Headcount cap for this organization. Defaults to 0 (uncapped) when omitted. |
{
"name": "Sales manager",
"section_ids": [
"63f8b0c4e4b0d3a2f8e4b0c4"
],
"organizations": [
{
"organization_id": "63f8b0c4e4b0d3a2f8e4b0c4",
"is_available": false,
"max_employee_count": 0
}
]
}Response
Same response shape as GET /position/get-by-id/{id}.
DELETE /position/delete/{id}
Soft-delete an HR position by ObjectId (sets is_deleted=true). Fails with 400 when at least one employee still holds the position — the error payload lists the blocking employees. Deleting an already-deleted position is a no-op.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Position 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.