Organization

RetrieveThe Organization API provides access to organizational hierarchy and filterstructure organizationsmanagement thatwithin the authenticatedGATE usersystem. hasThis endpoint allows you to retrieve information about your organization and any sub-organizations you have access to, includingwith sub-organizations.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. SupportsThis endpoint supports filtering by organizationvarious ID,organizational name,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 parentERP organization.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 ID
name	string	query	No	Filter organizations by organization name (supports partial matching). Case-insensitive search across organization names
parent	string	query	No	Filter organizations by parent organization IDID. Use this to get direct children of a specific organization
limit	integer	query	No	Number of results to return per page (default: 20)20, max: 100). Controls pagination page size
offset	integer	query	No	The initial index from which to return theresults. resultsUsed (default:for 0)pagination to skip previously retrieved records

ExamplecURL Request:Example:

curl -X GET "https://gate.zequenze.com/api/v1/organization/?name=marketingengineering&limit=1010" \
  -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_123456"org_12345",
      "name": "MarketingEngineering Department"Division",
      "parent": "org_000001"org_001",
      "parent_name": "Technology Department",
      "description": "GlobalSoftware marketingand operations"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-01-20T14:03-22T14:45:00Z"30Z",
      "member_count": 45,
      "sub_organizations"sub_organization_count": [3,
      "permissions": {
        "id"can_edit": "org_123457",true,
        "name"can_delete": "Digital Marketing",false,
        "parent"can_create_sub_orgs": "org_123456"true
      }
      ]
    },
    {
      "id": "org_123458"org_12346",
      "name": "MarketingFrontend Analytics"Engineering",
      "parent": "org_123456"org_12345",
      "parent_name": "Engineering Division",
      "description": "DataUser analysisinterface and reporting"user experience development",
      "status": "active",
      "level": 3,
      "full_path": "Acme Corp > Technology Department > Engineering Division > Frontend Engineering",
      "created_at": "2024-01-10T09:02-01T09:15:00Z",
      "updated_at": "2024-01-18T11:03-20T11:20:00Z"15Z",
      "member_count": 12,
      "sub_organizations"sub_organization_count": []0,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_create_sub_orgs": false
      }
    }
  ]
}

Response Codes:

Status	Description
200	OrganizationsSuccess retrieved- successfullyReturns the list of accessible organizations
401	Unauthorized - Invalid or missing Bearerauthentication token
403	Forbidden - User does not havelacks permission to view organizationsorganizational data
429404	TooNot Many RequestsFound - RateSpecified limitparent exceededorganization 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

• Use paginationImplement parametersPagination: (Always use the limit and offset) whenparameters dealing withfor large organizationorganizational hierarchiesstructures 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 Cache organizationHandle dataPermissions whenProperly: possibleAlways ascheck itthe typicallypermissions doesn'tobject changein frequentlyresponses 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 byStrategically: Use the parent parameter to retrievebuild specifichierarchical interfaces incrementally rather than loading the entire organizational levelstree at once Monitor Member Counts: Use the member_count field to understand organizational size and potentially adjust UI layouts or hierarchiesimplement additional pagination for member lists Use partialError nameHandling: matchingImplement torobust implementerror organizationhandling search functionality Monitor rate limits when making multiple requests in succession Handlefor 403 errors gracefullyresponses, as users may have limited organizational visibilitypermissions basedcan onchange, theiraffecting permissionswhich organizations a user can access