Skip to main content

Organization

The Organization API provides access to organizational hierarchy and structure management within the GATE system. This endpoint allows you to retrieve information about your organization and any sub-organizations you have access to, with flexible filtering options to find specific organizational units.

Base URL: https://gate.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Organization API is designed to help you navigate and understand the organizational structure within your GATE environment. Organizations in GATE represent hierarchical business units, departments, or divisions that help segment and organize resources, users, and permissions.

This API is particularly useful for:

  • Building organizational tree views in applications
  • Implementing role-based access controls based on organizational membership
  • Creating reports that need to be filtered by organizational units
  • Synchronizing organizational data with external systems
  • Managing multi-tenant applications where each organization represents a different client

The organizational hierarchy allows for nested structures where organizations can have parent-child relationships, enabling complex business structures to be accurately represented. When you query this endpoint, you'll receive information about your own organization and any sub-organizations you have permission to view, respecting the security boundaries defined in your GATE configuration.

Endpoints

GET /organization/

Description: Retrieves a list of organizations that the requesting user has access to, including their own organization and any sub-organizations. This endpoint supports filtering by various organizational attributes and includes pagination for handling large organizational structures efficiently.

Use Cases:

  • Display an organizational picker in a user interface
  • Generate reports filtered by specific organizational units
  • Sync organizational data with external HR or ERP systems
  • Build organizational charts or hierarchy visualizations
  • Filter data based on organizational membership

Full URL Example:

https://gate.zequenze.com/api/v1/organization/?parent=123&limit=20&offset=0

Parameters:

Parameter Type In Required Description
id string query No Filter organizations by specific ID. Useful when you need to verify existence or get details of a particular organization
name string query No Filter organizations by name (supports partial matching). Case-insensitive search across organization names
parent string query No Filter organizations by parent organization ID. Use this to get direct children of a specific organization
limit integer query No Number of results to return per page (default: 20, max: 100). Controls pagination page size
offset integer query No The initial index from which to return results. Used for pagination to skip previously retrieved records

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/organization/?name=engineering&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 25,
  "next": "https://gate.zequenze.com/api/v1/organization/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": "org_12345",
      "name": "Engineering Division",
      "parent": "org_001",
      "parent_name": "Technology Department",
      "description": "Software and hardware engineering teams",
      "status": "active",
      "level": 2,
      "full_path": "Acme Corp > Technology Department > Engineering Division",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-22T14:45:30Z",
      "member_count": 45,
      "sub_organization_count": 3,
      "permissions": {
        "can_edit": true,
        "can_delete": false,
        "can_create_sub_orgs": true
      }
    },
    {
      "id": "org_12346",
      "name": "Frontend Engineering",
      "parent": "org_12345",
      "parent_name": "Engineering Division",
      "description": "User interface and user experience development",
      "status": "active",
      "level": 3,
      "full_path": "Acme Corp > Technology Department > Engineering Division > Frontend Engineering",
      "created_at": "2024-02-01T09:15:00Z",
      "updated_at": "2024-03-20T11:20:15Z",
      "member_count": 12,
      "sub_organization_count": 0,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_create_sub_orgs": false
      }
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns the list of accessible organizations
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - User lacks permission to view organizational data
404 Not Found - Specified parent organization does not exist or is not accessible
422 Unprocessable Entity - Invalid query parameters provided

Common Use Cases

Use Case 1: Building an Organizational Hierarchy Widget

Retrieve the complete organizational structure to display in a tree view component, starting from the root and expanding sub-organizations as needed.

Use Case 2: Department-Specific Reporting

Filter data by specific organizational units to generate department-specific reports, using the organization ID as a filter parameter in other API calls.

Use Case 3: User Assignment Interface

Create a dropdown or selection interface for assigning users to organizations, showing only the organizations the current user has permission to manage.

Use Case 4: Multi-Tenant Application Setup

Use organizational data to implement tenant isolation, where each organization represents a separate customer or business unit with its own data space.

Use Case 5: Organizational Data Synchronization

Regularly sync organizational structure with external systems like HR platforms or directory services to maintain consistency across business applications.

Best Practices

  • Implement Pagination: Always use the limit and offset parameters for large organizational structures to prevent performance issues and timeout errors
  • Cache Organizational Data: Organization structures change infrequently, so implement appropriate caching strategies to reduce API calls and improve application performance
  • Handle Permissions Properly: Always check the permissions object in responses before enabling edit, delete, or create operations in your user interface
  • Use Full Path for Display: The full_path field provides a complete organizational hierarchy that's ideal for user-friendly displays and breadcrumb navigation
  • Filter Strategically: Use the parent parameter to build hierarchical interfaces incrementally rather than loading the entire organizational tree at once
  • Monitor Member Counts: Use the member_count field to understand organizational size and potentially adjust UI layouts or implement additional pagination for member lists
  • Error Handling: Implement robust error handling for 403 responses, as organizational permissions can change, affecting which organizations a user can access
Back to top