> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Falasefemi2/companyflow/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Balance by Type

> Get detailed balance for a specific leave type

Retrieve detailed leave balance information for the authenticated employee for a specific leave type and year. This provides a comprehensive breakdown including total days, used days, pending days, and available days.

## Authentication

Requires authentication with Bearer token. Available to:

* **Employee**
* **Manager**

<Note>
  This endpoint automatically uses the employee ID from the JWT token, so employees can only check their own balance.
</Note>

## Path Parameters

<ParamField path="leave_type_id" type="string" required>
  The unique identifier of the leave type (UUID format)

  **Example:** `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`
</ParamField>

## Query Parameters

<ParamField query="year" type="integer" required>
  The year to retrieve balance for (between 2020 and 2100)

  **Example:** `2025`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  Detailed leave balance object

  <Expandable title="LeaveBalance properties">
    <ResponseField name="id" type="string">
      Unique identifier for this leave balance record
    </ResponseField>

    <ResponseField name="employee_id" type="string">
      UUID of the employee
    </ResponseField>

    <ResponseField name="leave_type_id" type="string">
      UUID of the leave type
    </ResponseField>

    <ResponseField name="year" type="integer">
      The year this balance applies to
    </ResponseField>

    <ResponseField name="total_days" type="number">
      Total days allocated for this leave type (including carry forward)
    </ResponseField>

    <ResponseField name="used_days" type="number">
      Days already taken (approved leave)
    </ResponseField>

    <ResponseField name="pending_days" type="number">
      Days with pending approval
    </ResponseField>

    <ResponseField name="available_days" type="number">
      Days available to request (total - used - pending)
    </ResponseField>

    <ResponseField name="carried_forward_days" type="number">
      Days carried forward from previous year
    </ResponseField>

    <ResponseField name="leave_type" type="object">
      Associated leave type information

      <Expandable title="LeaveType properties">
        <ResponseField name="id" type="string">
          Leave type ID
        </ResponseField>

        <ResponseField name="name" type="string">
          Leave type name
        </ResponseField>

        <ResponseField name="code" type="string">
          Leave type code
        </ResponseField>

        <ResponseField name="days_allowed" type="number">
          Base days allowed per year
        </ResponseField>

        <ResponseField name="is_paid" type="boolean">
          Whether this is paid leave
        </ResponseField>

        <ResponseField name="color_code" type="string">
          Hex color code
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.companyflow.com/leave-balance/a1b2c3d4-e5f6-7890-abcd-ef1234567890?year=2025" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const leaveTypeId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
  const year = 2025;

  const response = await fetch(
    `https://api.companyflow.com/leave-balance/${leaveTypeId}?year=${year}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  leave_type_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  url = f'https://api.companyflow.com/leave-balance/{leave_type_id}'
  headers = {
      'Authorization': 'Bearer YOUR_TOKEN'
  }
  params = {
      'year': 2025
  }

  response = requests.get(url, headers=headers, params=params)
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true,
    "data": {
      "id": "bal-001-uuid",
      "employee_id": "987e6543-e21b-12d3-a456-426614174000",
      "leave_type_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "year": 2025,
      "total_days": 22,
      "used_days": 5,
      "pending_days": 1.5,
      "available_days": 15.5,
      "carried_forward_days": 2,
      "leave_type": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Annual Leave",
        "code": "AL",
        "days_allowed": 20,
        "is_paid": true,
        "color_code": "#3B82F6"
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-03-03T10:30:00Z"
    }
  }
  ```

  ```json 400 - Bad Request (Invalid leave type ID) theme={null}
  {
    "success": false,
    "message": "invalid leave type id"
  }
  ```

  ```json 400 - Bad Request (Missing year) theme={null}
  {
    "success": false,
    "message": "year is required"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "success": false,
    "message": "unauthorized"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "success": false,
    "message": "internal server error"
  }
  ```
</ResponseExample>

## Balance Breakdown

The response provides a complete picture of leave balance:

<Steps>
  <Step title="Total Days">
    Base allocation (e.g., 20 days) + carried forward days (e.g., 2 days) = 22 total days
  </Step>

  <Step title="Used Days">
    Days already taken through approved leave requests (e.g., 5 days)
  </Step>

  <Step title="Pending Days">
    Days requested but awaiting approval (e.g., 1.5 days)
  </Step>

  <Step title="Available Days">
    Total days - used days - pending days = 15.5 days available
  </Step>
</Steps>

## Comparison with Check Balance

<CardGroup cols={2}>
  <Card title="Check Balance" icon="gauge" href="/api/leaves/balances/check">
    Returns only the **available days** number (quick check)
  </Card>

  <Card title="Get Balance by Type" icon="chart-pie" href="/api/leaves/balances/by-type">
    Returns **complete breakdown** with all balance components
  </Card>
</CardGroup>

## Use Cases

This endpoint is ideal for:

* **Detailed balance display**: Show comprehensive leave status in employee portals
* **Leave request forms**: Display full context before submission
* **Balance analytics**: Track usage patterns and trends
* **Approval workflows**: Provide complete balance information to approvers

<Info>
  This endpoint includes the leave type configuration (name, code, color) making it perfect for building rich UI components without additional API calls.
</Info>

## Related Endpoints

* [Check Balance](/api/leaves/balances/check) - Quick available days check
* [Get Employee Balances](/api/leaves/balances/employee) - All balances for an employee
* [Request Leave](/api/leaves/create) - Submit a new leave request