Organization

Endpoints Summary

Method	Path	Swagger
`GET`	`/organization/`	Swagger ↗

The Organization API provides access to your organization hierarchy, allowing you to retrieve information about your primary organization and all sub-organizations you have access to. This endpoint is essential for understanding organizational structure, filtering data by organization, 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 organizational data within the GATE 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 useful for:

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 data access is organization-based

The endpoint returns paginated results and supports filtering by organization ID, name, and parent organization, making it flexible for various integration scenarios. Each organization includes metadata such as country, platform type, and hierarchical relationships through the parent organization structure.

Endpoints

GET /organization/

Description: Retrieves a list of organizations that the authenticated user has access to, including their primary organization and any sub-organizations. This endpoint supports filtering and pagination, making it suitable for both complete organization lists and targeted searches.

Use Cases:

Populating organization dropdown menus in applications
Building organizational charts and hierarchy visualizations
Filtering datasets by specific organizations
Audit trails showing which organizations a user can access
Multi-tenant application 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 by parent organization ID to get sub-organizations
limit	integer	query	No	Number of results to return per page (default pagination applies)
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&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": "Acme Corporation Headquarters",
      "short_name": "acme-hq",
      "is_active": true,
      "deleted": false,
      "country_code": "US",
      "platform": 1,
      "description": "Main headquarters for Acme Corporation",
      "parent": null,
      "parent_obj": null,
      "created": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "name": "Acme West Coast Division",
      "short_name": "acme-west",
      "is_active": true,
      "deleted": false,
      "country_code": "US",
      "platform": 2,
      "description": "West Coast operations division",
      "parent": 1,
      "parent_obj": {
        "id": 1,
        "name": "Acme Corporation Headquarters",
        "short_name": "acme-hq",
        "is_active": true,
        "deleted": false,
        "country_code": "US",
        "platform": 1,
        "description": "Main headquarters for Acme Corporation",
        "parent": null,
        "created": "2024-01-15T10:30:00Z"
      },
      "created": "2024-02-01T14:20:00Z"
    },
    {
      "id": 3,
      "name": "Acme European Office",
      "short_name": "acme-eu",
      "is_active": true,
      "deleted": false,
      "country_code": "DE",
      "platform": 4,
      "description": "European operations center",
      "parent": 1,
      "parent_obj": {
        "id": 1,
        "name": "Acme Corporation Headquarters",
        "short_name": "acme-hq",
        "is_active": true,
        "deleted": false,
        "country_code": "US",
        "platform": 1,
        "description": "Main headquarters for Acme Corporation",
        "parent": null,
        "created": "2024-01-15T10:30:00Z"
      },
      "created": "2024-03-10T09:15:00Z"
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns paginated list of organizations
401	Unauthorized - Invalid or missing authentication token
403	Forbidden - User doesn'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 active organizations to populate a dropdown menu in your application, allowing users to filter data or switch context between organizations.

https://gate.zequenze.com/api/v1/organization/?is_active=true&limit=100

Use Case 2: Loading Sub-Organizations

Get all sub-organizations under a specific parent organization to build hierarchical views or organizational charts.

https://gate.zequenze.com/api/v1/organization/?parent=1&is_active=true

Use Case 3: Organization Search

Search for organizations by name to implement organization lookup functionality in your application.

https://gate.zequenze.com/api/v1/organization/?name=west&limit=10

Use Case 4: 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

Use pagination wisely: Set appropriate limit values (10-50 items) to balance performance and user experience. Don't request all organizations at once if you have many.
Cache organization data: Organization structures typically don't change frequently, so implement client-side caching to reduce API calls and improve application performance.
Handle hierarchy properly: When working with parent-child relationships, use the parent_obj nested data to avoid additional API calls for parent organization details.
Filter inactive organizations: In most user-facing scenarios, filter for is_active=true to hide deactivated organizations from users unless specifically managing organization status.
Implement proper error handling: Always check for authentication errors (401) and handle cases where users might lose access to organizations due to permission changes.
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.