# Organization

## Endpoints Summary

| Method | Path | Swagger |
|:------:|------|:-------:|
| `GET` | [`/organization/`](#get-organization) | <a href="https://gate.zequenze.com/api#/organization/organization_list" target="_blank">Swagger ↗</a> |

---
> 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

<a id="get-organization"></a>

### 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:**
```bash
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:**
```bash
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:**
```json
{
  "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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

---