************************************************
``GET`` List Applicants in a Track
************************************************

This API retrieves a paginated list of applicants for a specific track with search and filter support.

Request URL
=============

.. code-block::
    
    GET /tracks/<track_id>/applicants

.. warning::
    
    Make sure to add your API key in Header of the request

Parameters
===========

+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| Parameter         | Type             | Description                                                                                       |
+===================+==================+===================================================================================================+
| track_id          | *integer*        | ID of the track from which applicants are to be fetched.                                          |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| page              | *integer*        | Page number for pagination. Default is ``1``.                                                     |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| per_page          | *integer*        | Number of records per page. Allowed range is ``1`` to ``200``. Default is ``25``.                 |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| name              | *string*         | Case-insensitive partial filter on applicant name.                                                |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| email             | *string*         | Case-insensitive partial filter on applicant email.                                               |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| stage_id          | *string*         | Filter applicants currently in the given stage ID.                                                |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| stage_status      | *string*         | Filter by stage status. Allowed values: ``Pending``, ``Completed``.                               |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| candidate_id      | *integer*        | Filter by person-level candidate ID.                                                              |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| application_id    | *integer*        | Filter by application ID within the track.                                                        |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| sort_by           | *string*         | Sort field. Allowed values: ``date_added``, ``last_updated_at``, ``name``, ``email``.             |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| sort_order        | *string*         | Sort direction. Allowed values: ``asc``, ``desc``.                                                |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| from_date         | *date*           | Inclusive start date in ``YYYY-MM-DD`` format.                                                    |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| to_date           | *date*           | Inclusive end date in ``YYYY-MM-DD`` format.                                                      |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+
| timeframe_field   | *string*         | Date field used for range filters. Allowed values: ``date_added``, ``last_updated_at``.           |
+-------------------+------------------+---------------------------------------------------------------------------------------------------+

Response
==========

- A JSON response containing paginated applicants and pagination metadata.

.. code-block:: JSON

    {
        "data": [
            {
                "application_id": "integer",
                "candidate_id": "integer",
                "name": "string",
                "email": "string",
                "stage_id": "string",
                "stage_name": "string",
                "stage_type": "string",
                "stage_status": "string",
                "score": "number",
                "date_added": "string",
                "last_updated_at": "string"
            }
        ],
        "pagination": {
            "page": "integer",
            "per_page": "integer",
            "total": "integer",
            "total_pages": "integer",
            "has_next": "boolean",
            "has_prev": "boolean"
        }
    }