*********************************************
``GET`` Candidate's AI Interview Report
*********************************************

This API retrieves the AI Interview report of the candidate.

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

.. code-block:: 

    GET /ai-interviews/report/<response_id>

or

.. code-block:: text

    GET /ai-interviews/report?custom_field_id=<custom_field_id>

.. warning::

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

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

+---------------------+------------------+---------------------------------------------------------------------------------------------------+
| Parameter           | Type             | Description                                                                                       |
+=====================+==================+===================================================================================================+
| response_id         | *integer*        | Response ID of the candidate for the AI Interview                                                 |
| *(optional)*        |                  | Required if ``custom_field_id`` is not provided.                                                  |
+---------------------+------------------+---------------------------------------------------------------------------------------------------+

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

+---------------------+------------------+-----------------------------------------------------------------------------------------------------+
| Parameter           | Type             | Description                                                                                         |
+=====================+==================+=====================================================================================================+
| custom_field_id     | *string*         | The custom identifier set during invite creation. Use this instead of ``response_id``.              |
| *(optional)*        |                  | Required if ``response_id`` is not provided in the path.                                            |
|                     |                  |                                                                                                     |
|                     |                  | **Example:** ``GET /ai-interviews/report?custom_field_id=CAND-2025-001``                            |
+---------------------+------------------+-----------------------------------------------------------------------------------------------------+
| is_downloadable     | *boolean*        | If true, includes downloadable URLs for the interview session recordings (if available).            |
| *(optional)*        |                  |                                                                                                     |
|                     |                  | **Example:** ``GET /ai-interviews/report/7421?is_downloadable=true``                                |
+---------------------+------------------+-----------------------------------------------------------------------------------------------------+

Response
===========

- A JSON response containing information about the candidate's AI Interview report, given that the interview is completed.

.. code-block:: JSON

    {
        "ai_interview_id": "integer",
        "ai_interview_name": "string",
        "candidate_email": "string",
        "candidate_id": "integer",
        "candidate_name": "string",
        "candidate_summary": "string",
        "completed_date": "string",
        "integrity_score": "float",
        "invite_status": "string",
        "pdf_link": "string",
        "recommendation": "string",
        "response_id": "integer",
        "custom_field_id": "string",
        "score": "integer",
        "report_link": "string",
        "interview_recording": {
            "session1": "string",
            "session2": "string"
        },
        "skill_wise_scores": {
            "must_haves": [
                {
                    "score": "integer",
                    "skill_name": "string"
                }
            ],
            "nice_to_haves": [
                {
                    "score": "integer",
                    "skill_name": "string"
                }
            ]
        },
        "conversation": [
            {
                "content": "string",
                "mode": "string",
                "role": "string",
                "timestamp": "integer"
            }
        ]
    }

.. note::

    - ``candidate_summary`` is an auto-generated summary that evaluates the candidate's performance based on AI scoring.
    - ``recommendation`` indicates whether the candidate is recommended for the role based on skill alignment and scoring.
    - ``integrity_score`` is measured on a scale of 0 - 10.
    - ``skill_wise_scores`` are grouped under `must_haves` and `nice_to_haves`, based on the AI Interview Plan configuration.
    - ``interview_recording`` is a dictionary containing the URLs of the interview recordings for each session. Session is a string like ``1755695988585`` which is the timestamp of the session.
    - ``conversation`` is an array of message objects representing the interview dialogue. Each message contains:

      - ``content``: The message text.
      - ``mode``: Either "code" or "default".
      - ``role``: "user" for candidate, "assistant" for interviewer.
      - ``timestamp``: Unix timestamp in milliseconds.

- A JSON response when the candidate has not completed the AI Interview.

.. code-block:: JSON

    {
        "ai_interview_id": "integer",
        "ai_interview_name": "string",
        "candidate_email": "string",
        "candidate_id": "integer",
        "candidate_name": "string",
        "invite_status": "string",
        "response_id": "integer",
        "custom_field_id": "string"
    }

.. note::

    - The value for ``invite_status`` will be ``Pending`` if the candidate has not yet started the AI Interview.
    - ``custom_field_id`` is only included in the response if it was set during invite creation and the report is fetched using ``custom_field_id``.