Organization

Endpoints Summary

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:

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:

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.