************************************************
``GET`` Candidates Invited for an Assessment V2
************************************************

This API retrieves candidates invited to an assessment, including assessment
metadata and detailed report data for candidates who have completed it.
Candidates can be filtered by their current invitation status.

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

.. code-block::

    GET /assessments/invited/v2/<assessment_id>

.. warning::

    Make sure to add your API key in the request header.

Path Parameters
================

+-----------------------+------------------+---------------------------------------------------------------------------------------------------+
| Parameter             | Type             | Description                                                                                       |
+=======================+==================+===================================================================================================+
| assessment_id         | *integer*        | Assessment ID for which invited candidates are to be fetched.                                     |
+-----------------------+------------------+---------------------------------------------------------------------------------------------------+

Query Parameters
=================

+-----------------------+------------------+---------------------------------------------------------------------------------------------------+
| Parameter             | Type             | Description                                                                                       |
+=======================+==================+===================================================================================================+
| status                | *string*         | Optional. Filters candidates by ``Pending``, ``Started``, ``Completed``, ``Expired``, or          |
|                       |                  | ``Revoked``.                                                                                      |
+-----------------------+------------------+---------------------------------------------------------------------------------------------------+
| page                  | *integer*        | Optional. Page number, starting at ``1``. Defaults to ``1``.                                      |
+-----------------------+------------------+---------------------------------------------------------------------------------------------------+
| limit                 | *integer*        | Optional. Candidates per page. Defaults to ``25``; values must be between ``1`` and ``200``.      |
+-----------------------+------------------+---------------------------------------------------------------------------------------------------+

Response
==========

The response contains assessment details and the invited candidates. A
``report`` object is included only when report data is available for a
completed candidate. Report links expire after seven days.

.. code-block:: JSON

    {
        "assessment_id": 123,
        "assessment_name": "Software Engineer Assessment",
        "cut_off": 60,
        "total_invited_candidates": 54,
        "candidates": [
            {
                "candidate_id": 456,
                "email": "candidate@example.com",
                "name": "Candidate Name",
                "report_id": 789,
                "invite_status": "Completed",
                "report": {
                    "candidate_id": 456,
                    "email": "candidate@example.com",
                    "name": "Candidate Name",
                    "report_id": 789,
                    "overall_percentage": 82.5,
                    "integrity": "Clear",
                    "qualification": "Qualified",
                    "report_link": "https://example.com/signed-report-link",
                    "completed_date": "2026-07-13T10:30:00",
                    "sections": [
                        {
                            "section_name": "Programming",
                            "percentage": 85.0,
                            "skills": [
                                {
                                    "skill": "Python",
                                    "percentage": 90.0
                                }
                            ]
                        }
                    ]
                }
            },
            {
                "candidate_id": 457,
                "email": "pending.candidate@example.com",
                "name": "Pending Candidate",
                "report_id": 790,
                "invite_status": "Pending"
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 25,
            "total": 40,
            "total_pages": 2,
            "has_next": true,
            "has_previous": false
        }
    }

``total_invited_candidates`` is the count of all invitations before applying
the optional status filter. ``pagination.total`` is the count after filtering.
The ``integrity`` field is a label: ``Clear``, ``Review Needed``, or ``Action
Required``.

If no candidates match the request, the API returns assessment details, an
empty ``candidates`` array, pagination metadata, and the message ``No
candidates found``.

Response Status Codes
======================

+-----------------------+---------------------------------------------------------------------------------------------------+
| Status Code           | Description                                                                                       |
+=======================+===================================================================================================+
| 200                   | Candidates were retrieved successfully, including an empty result.                                |
+-----------------------+---------------------------------------------------------------------------------------------------+
| 400                   | The supplied ``status``, ``page``, or ``limit`` value is invalid.                                 |
+-----------------------+---------------------------------------------------------------------------------------------------+
| 404                   | The assessment was not found.                                                                     |
+-----------------------+---------------------------------------------------------------------------------------------------+
| 500                   | Candidate information could not be fetched.                                                       |
+-----------------------+---------------------------------------------------------------------------------------------------+