Organization

Endpoints Summary

Method Path Swagger GET /organization/ Swagger ↗

---

The Organization API provides access to organizationalyour hierarchyorganization data,hierarchy, allowing usersyou to retrieve information about theiryour primary organization and all associatedsub-organizations sub-organizations.you have access to. This endpoint is essential for understanding organizational structure, managing multi-tenant applications, and filtering data by organizationalorganization, scope.and building organization-aware applications.

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 hierarchiesdata within the GATE system.platform. Organizations in GATE represent hierarchical business entities that can contain sub-organizations, making it ideal for managing multi-location businesses, franchises, or enterprise divisions.

This API is particularly valuableuseful forfor:

Building organization selectors in user interfaces Filtering other API data by organization Understanding organizational hierarchy and relationships Creating reports and analytics grouped by organization Managing multi-tenant applications where users need to understand their organizational context anddata access datais 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 deletedorganization-based

CommonThe Useendpoint Cases:

returns

paginated Buildingresults organizationaland selectionsupports dropdowns in applications Filtering datafiltering by organizationalorganization scopeID, Displayingname, organizationaland hierarchiesparent inorganization, dashboardsmaking Managingit multi-tenantflexible accessfor controlsvarious Generatingintegration organization-specificscenarios. reportsEach organization includes metadata such as country, platform type, and hierarchical relationships through the parent organization structure.

---

Endpoints

GET /organization/

Description: Retrieves a paginated list of organizations that the authenticated user has access to, including their primary organization and allany sub-organizations. This endpoint supports filtering byand variouspagination, making it suitable for both complete organization attributeslists and providestargeted comprehensive organization details including hierarchy information.searches.

Use Cases:

• PopulatePopulating organization selectiondropdown menus in user interfacesapplications
• BuildBuilding organizational charts and hierarchy visualizations
• FilterFiltering other API callsdatasets by organizationspecific scopeorganizations
• DisplayAudit user'strails accessibleshowing which organizations ina multi-user can access

Multi-tenant applicationsapplication setup and organization-based routing

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 to get sub-organizations
limit	integer	query	No	Number of results to return per page (default:default varies)pagination applies)
offset	integer	query	No	The initial index from which to return results (for pagination)pagination

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/organization/?limit=10&is_active=true"offset=0" \
  -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": "GlobalAcme Corporation Headquarters",
      "short_name": "hq-global"acme-hq",
      "is_active": true,
      "deleted": false,
      "country_code": "US",
      "platform": 31,1,
      "description": "Main headquarters managingfor globalAcme operations"Corporation",
      "parent": null,
      "parent_obj": null,
      "created": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "name": "NorthAcme AmericaWest Coast Division",
      "short_name": "na-division"acme-west",
      "is_active": true,
      "deleted": false,
      "country_code": "US",
      "platform": 15,2,
      "description": "NorthWest AmericanCoast operations division",
      "parent": 1,
      "parent_obj": {
        "id": 1,
        "name": "GlobalAcme Corporation Headquarters",
        "short_name": "hq-global"acme-hq",
        "is_active": true,
        "deleted": false,
        "country_code": "US",
        "platform": 31,1,
        "description": "Main headquarters managingfor globalAcme operations"Corporation",
        "parent": null,
        "created": "2024-01-15T10:30:00Z"
      },
      "created": "2024-01-20T14:45:02-01T14:20:00Z"
    },
    {
      "id": 3,
      "name": "Acme European Division"Office",
      "short_name": "eu-division"acme-eu",
      "is_active": true,
      "deleted": false,
      "country_code": "DE",
      "platform": 7,4,
      "description": "European operations division"center",
      "parent": 1,
      "parent_obj": {
        "id": 1,
        "name": "GlobalAcme Corporation Headquarters",
        "short_name": "hq-global"acme-hq",
        "is_active": true,
        "deleted": false,
        "country_code": "US",
        "platform": 31,1,
        "description": "Main headquarters managingfor globalAcme operations"Corporation",
        "parent": null,
        "created": "2024-01-15T10:30:00Z"
      },
      "created": "2024-01-22T09:03-10T09: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 organizationlist listof organizations
401	Unauthorized - Invalid or missing authentication token
403	Forbidden - User lacksdoesn't have permission to access organizations
500	Internal Server Error - Server-side error occurred

---

Common Use Cases

Use Case 1: Building Organization Selector

Retrieve all accessibleactive organizations to populate a dropdown menu forin filteringyour application, allowing users to filter data or switch context switchingbetween in multi-tenant applications.

Example:organizations.

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

Use Case 2: DisplayingLoading Organizational HierarchySub-Organizations

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

RetrieveGet all child sub-organizations under a specific parent organization forto departmentalbuild views.

hierarchical

Example:views or organizational charts.

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

Use Case 5:3: Organization Search

Search for organizations by name to helpimplement usersorganization quicklylookup findfunctionality specificin organizationalyour units.

Example:application.

curl -X GET "https://gate.zequenze.com/api/v1/organization/?name=division"west&limit=10
\

-H

Use "Authorization:Case Bearer4: YOUR_API_TOKEN"Paginated Organization List

Load organizations in batches for large datasets, implementing proper pagination in your user interface.

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

Use Case 5: Organization Validation

Verify if a specific organization exists and is accessible to the current user by filtering by ID.

https://gate.zequenze.com/api/v1/organization/?id=123

---

Best Practices

• PaginationUse pagination wisely: Always useSet appropriate limit values (10-50 items) to balance performance and offsetuser parametersexperience. forDon't largerequest organizationalall structuresorganizations toat maintainonce performanceif you have many.

• Caching: Cache organization data: locally when possible, as organizationalOrganization structures typically don't change frequentlyfrequently, so implement client-side caching to reduce API calls and improve application performance.

• HierarchyHandle Navigationhierarchy properly: UseWhen working with parent-child relationships, use the parent_obj fieldnested data to build efficient tree structures withoutavoid additional API calls for parent organization details.

• ActiveFilter Filteringinactive organizations: FilterIn bymost user-facing scenarios, filter for is_active=true into user-facinghide interfacesdeactivated organizations from users unless you specifically needmanaging toorganization showstatus.

  inactive organizations

• Platform Filtering: Decode platform bitwise values to show relevant organizations based on the current application context

Error Handling: Implement proper error handling: Always check for authentication errors (401) and handle cases where organizational access permissions may change Security: Never expose organization IDs or structure information to users whomight shouldn't havelose access to thatorganizations leveldue ofto organizationalpermission datachanges.

Use short_name for URLs: The short_name field is designed for use in URLs and identifiers - it's URL-safe and human-readable.

Respect platform values: The platform field uses bitwise flags (1, 2, 4, 8, 16, 32, 64) - understand your platform requirements before filtering on this field.

---