Skip to main content

​
Overview

The Organization Management API provides endpoints for managing organizational structures, including departments, divisions, and hierarchical relationships. Organizations help structure users and define reporting relationships within jshERP. Base Path: /organization
Organizations support hierarchical structures with parent-child relationships, enabling complex organizational charts.

​
CRUD Operations

​
Get Organization Information

GET /organization/info?id={id}
Retrieves detailed information for a specific organization.
​
id
long
required
Organization ID
​
code
integer
Response status code (200 for success)
​
info
object
Organization entity object
curl -X GET "http://localhost:9999/jshERP-boot/organization/info?id=1" \
  -H "Authorization: Bearer {token}"

​
Create Organization

POST /organization/add
Creates a new organization.
​
orgNo
string
required
Organization code/number (must be unique)
​
orgAbr
string
required
Organization abbreviation or short name
​
parentId
long
Parent organization ID (omit or set to null for root-level organization)
​
sort
string
Sort order for display purposes
​
remark
string
Additional remarks or description
{
  "orgNo": "ORG002",
  "orgAbr": "Marketing",
  "parentId": 1,
  "sort": "2",
  "remark": "Marketing and promotion team"
}

​
Update Organization

PUT /organization/update
Updates an existing organization’s information.
​
id
long
required
Organization ID
​
orgNo
string
Organization code/number
​
orgAbr
string
Organization abbreviation
​
parentId
long
Parent organization ID
​
sort
string
Sort order
​
remark
string
Additional remarks
{
  "id": 2,
  "orgAbr": "Marketing & Sales",
  "remark": "Combined marketing and sales division"
}

​
Delete Organization

DELETE /organization/delete?id={id}
Deletes an organization (soft delete).
Deleting an organization with child organizations or associated users may fail. Remove dependencies first.
​
id
long
required
Organization ID to delete

​
Batch Delete Organizations

DELETE /organization/deleteBatch?ids={ids}
Deletes multiple organizations in a single operation.
​
ids
string
required
Comma-separated organization IDs (e.g., “1,2,3”)

​
Organization Hierarchy

​
Get Organization Tree

GET /organization/getOrganizationTree?id={id}
Retrieves a hierarchical tree structure of organizations starting from a specific node.
​
id
long
required
Root organization ID (use null or 0 to get the entire tree)
​
array
array
Array of tree node objects with nested children
curl -X GET "http://localhost:9999/jshERP-boot/organization/getOrganizationTree?id=0" \
  -H "Authorization: Bearer {token}"

​
Get All Organization Tree by User

GET /organization/getAllOrganizationTreeByUser
Retrieves the complete organization tree based on current user’s permissions.
Only users with public role type can access the full organization tree. Other users will receive an empty array.
​
array
array
Array of tree node objects (empty if user doesn’t have public role)
curl -X GET "http://localhost:9999/jshERP-boot/organization/getAllOrganizationTreeByUser" \
  -H "Authorization: Bearer {token}"

​
Find Organization by ID

GET /organization/findById?id={id}
Retrieves organization information including parent organization name.
​
id
long
required
Organization ID
​
code
integer
Response status code
​
data
object
Organization details with parent information
{
  "code": 200,
  "data": {
    "id": 2,
    "orgAbr": "Regional Sales",
    "parentId": 1,
    "orgParentName": "Sales Dept",
    "orgNo": "ORG002",
    "sort": "1",
    "remark": "Regional sales team"
  }
}

​
Validation

​
Check Organization Name Exists

GET /organization/checkIsNameExist?id={id}&name={name}
Checks if an organization name (abbreviation) is already in use.
​
id
long
required
Organization ID (0 for new organization)
​
name
string
Organization abbreviation to check
​
status
boolean
true if name exists, false otherwise
curl -X GET "http://localhost:9999/jshERP-boot/organization/checkIsNameExist?id=0&name=Finance" \
  -H "Authorization: Bearer {token}"

​
Data Models

​
Organization Entity

​
id
long
Unique organization identifier
​
orgNo
string
Organization code/number (must be unique within tenant)
​
orgAbr
string
Organization abbreviation or short name (displayed in UI)
​
parentId
long
Parent organization ID:
  • null or 0: Root-level organization
  • Other value: Child organization
​
sort
string
Sort order for display purposes (lower numbers appear first)
​
remark
string
Additional remarks or description
​
createTime
date
Timestamp when the organization was created
​
updateTime
date
Timestamp of last update
​
tenantId
long
Associated tenant ID (for multi-tenancy)
​
deleteFlag
string
Soft delete flag (used internally)

​
Hierarchical Structure

​
Understanding Parent-Child Relationships

Organizations support unlimited depth of hierarchy: 
Company (parentId: null)
├── Sales Department (parentId: 1)
│   ├── Regional Sales (parentId: 2)
│   └── Online Sales (parentId: 2)
├── Operations (parentId: 1)
│   ├── Warehouse (parentId: 3)
│   └── Logistics (parentId: 3)
└── Finance (parentId: 1)

​
Root Organizations

  • Root organizations have parentId set to null or 0
  • Typically represent top-level divisions or departments
  • Can have multiple root organizations per tenant

​
Child Organizations

  • Child organizations reference their parent via parentId
  • Can themselves be parents to other organizations
  • Inherit tenant from parent organization

​
Common Use Cases

​
Creating an Organization Hierarchy

  1. Create root organization with parentId: null
  2. Create child organizations referencing the root’s ID
  3. Continue creating nested levels as needed
  4. Use sort field to control display order at each level

​
Moving an Organization

  1. Get the organization’s current information
  2. Update the organization with a new parentId
  3. Verify the change using /organization/getOrganizationTree

​
Restructuring Organizations

  1. Get the complete tree structure
  2. Identify organizations to move or delete
  3. Update parent relationships
  4. Remove obsolete organizations

​
Best Practices

Organization Codes: Use a consistent naming scheme for organization codes (e.g., DEPT001, DEPT002) to maintain order and clarity.
Naming: Keep organization abbreviations short and meaningful. They are displayed throughout the UI.
Circular References: Never set an organization’s parent to itself or to one of its descendants. This will cause errors in tree operations.
User Assignment: Users can be assigned to organizations through the user management API. This establishes their position in the organizational structure.

​
Integration with Other Features

​
User Management

  • Users are assigned to organizations
  • Organization structure determines user hierarchy
  • Used for approval workflows and reporting lines

​
Permissions

  • Organization membership can affect data access
  • Users may only see data from their organization and below
  • Role permissions combine with organization structure

​
Reporting

  • Organization structure used for departmental reports
  • Hierarchical rollup of statistics
  • Department-level analytics

​
Tree Operations

The organization tree structure is commonly used in:
  • Organization Pickers: Select departments in forms
  • User-Organization Trees: Combined view showing users within organizations
  • Permission Assignment: Grant permissions by organization
  • Reporting Hierarchies: Structure reports by department

​
Error Codes

CodeDescription
200Success
500Internal server error
All endpoints return a standard response format with code and data fields. Check the code field to determine success or failure.

​
Performance Considerations

Tree Loading: For large organization structures, consider loading the tree incrementally rather than all at once.
Caching: Organization structures typically change infrequently. Consider caching tree structures to improve performance.

Build docs developers (and LLMs) love

Get started for freeTalk to us