Skip to main content

Organization

The Organization API provides access to organizational hierarchy data, allowing users to retrieve information about their organization and all associated sub-organizations. This endpoint is essential for understanding organizational structure, managing multi-tenant applications, and filtering data by organizational scope.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Organization API enables developers to access and navigate organizational hierarchies within the GATE system. This API is particularly valuable for multi-tenant applications where users need to understand their organizational context and access data scoped to their organization and its subsidiaries.

Key Concepts:

  • Hierarchical Structure: Organizations can have parent-child relationships, creating multi-level organizational trees
  • Platform Support: Organizations can be associated with different platforms (mobile, web, desktop, etc.)
  • Active Status: Organizations can be marked as active or inactive, affecting visibility and access
  • Soft Deletion: Deleted organizations remain in the system but are marked as deleted

Common Use Cases:

  • Building organizational selection dropdowns in applications
  • Filtering data by organizational scope
  • Displaying organizational hierarchies in dashboards
  • Managing multi-tenant access controls
  • Generating organization-specific reports

Endpoints

GET /organization/

Description: Retrieves a paginated list of organizations that the authenticated user has access to, including their primary organization and all sub-organizations. This endpoint supports filtering by various organization attributes and provides comprehensive organization details including hierarchy information.

Use Cases:

  • Populate organization selection menus in user interfaces
  • Build organizational charts and hierarchy visualizations
  • Filter other API calls by organization scope
  • Display user's accessible organizations in multi-tenant applications

Full URL Example:

https://gate.zequenze.com/api/v1/organization/?name=headquarters&is_active=true&limit=20&offset=0

Parameters:

Parameter Type In Required Description
id string query No Filter organizations by specific ID
name string query No Filter organizations by name (supports partial matching)
parent string query No Filter organizations by parent organization ID
limit integer query No Number of results to return per page (default: varies)
offset integer query No The initial index from which to return results (for pagination)

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/organization/?limit=10&is_active=true" \
  -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": 1,
      "name": "Global Headquarters",
      "short_name": "hq-global",
      "is_active": true,
      "deleted": false,
      "country_code": "US",
      "platform": 31,
      "description": "Main headquarters managing global operations",
      "parent": null,
      "parent_obj": null,
      "created": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "name": "North America Division",
      "short_name": "na-division",
      "is_active": true,
      "deleted": false,
      "country_code": "US",
      "platform": 15,
      "description": "North American operations division",
      "parent": 1,
      "parent_obj": {
        "id": 1,
        "name": "Global Headquarters",
        "short_name": "hq-global",
        "is_active": true,
        "deleted": false,
        "country_code": "US",
        "platform": 31,
        "description": "Main headquarters managing global operations",
        "parent": null,
        "created": "2024-01-15T10:30:00Z"
      },
      "created": "2024-01-20T14:45:00Z"
    },
    {
      "id": 3,
      "name": "European Division",
      "short_name": "eu-division",
      "is_active": true,
      "deleted": false,
      "country_code": "DE",
      "platform": 7,
      "description": "European operations division",
      "parent": 1,
      "parent_obj": {
        "id": 1,
        "name": "Global Headquarters",
        "short_name": "hq-global",
        "is_active": true,
        "deleted": false,
        "country_code": "US",
        "platform": 31,
        "description": "Main headquarters managing global operations",
        "parent": null,
        "created": "2024-01-15T10:30:00Z"
      },
      "created": "2024-01-22T09:15:00Z"
    }
  ]
}

Platform Values: The platform field uses bitwise flags that can be combined:

  • 1: Mobile App
  • 2: Web Application
  • 4: Desktop Application
  • 8: API Access
  • 16: IoT Devices
  • 32: Third-party Integrations
  • 64: Administrative Tools

Response Codes:

Status Description
200 Success - Returns paginated organization list
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - User lacks permission to access organizations
500 Internal Server Error - Server-side error occurred

Common Use Cases

Use Case 1: Building Organization Selector

Retrieve all accessible organizations to populate a dropdown menu for filtering or context switching in multi-tenant applications.

Example:

curl -X GET "https://gate.zequenze.com/api/v1/organization/?is_active=true&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 2: Displaying Organizational Hierarchy

Fetch organizations and use the parent_obj data to build hierarchical tree views showing organizational structure.

Example:

curl -X GET "https://gate.zequenze.com/api/v1/organization/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 3: Regional Organization Filtering

Filter organizations by country or region to display location-specific data.

Example:

curl -X GET "https://gate.zequenze.com/api/v1/organization/?country_code=US" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 4: Finding Sub-organizations

Retrieve all child organizations under a specific parent organization for departmental views.

Example:

curl -X GET "https://gate.zequenze.com/api/v1/organization/?parent=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 5: Organization Search

Search for organizations by name to help users quickly find specific organizational units.

Example:

curl -X GET "https://gate.zequenze.com/api/v1/organization/?name=division" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Best Practices

  • Pagination: Always use appropriate limit and offset parameters for large organizational structures to maintain performance
  • Caching: Cache organization data locally when possible, as organizational structures don't change frequently
  • Hierarchy Navigation: Use the parent_obj field to build efficient tree structures without additional API calls
  • Active Filtering: Filter by is_active=true in user-facing interfaces unless you specifically need to show inactive organizations
  • Platform Filtering: Decode platform bitwise values to show relevant organizations based on the current application context
  • Error Handling: Implement proper error handling for cases where organizational access permissions may change
  • Security: Never expose organization IDs or structure information to users who shouldn't have access to that level of organizational data
Back to top