***********************************************
``PATCH`` Revoke Candidate AI Interview Invite
***********************************************

This API revokes a candidate's invite for a specified **AI Interview**.

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

.. code-block::

    PATCH /ai-interviews/invite/revoke

Body Parameters
================

.. code-block:: JSON

    {
        "response_id": "integer",
        "notify_candidate": "boolean"
    }

.. warning::

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

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

+-------------------+------------------+-----------------------------------------------------------------------------------------+
| Parameter         | Type             | Description                                                                             |
+===================+==================+=========================================================================================+
| response_id       | *integer*        | The Response ID of the candidate invite that needs to be revoked.                       |
+-------------------+------------------+-----------------------------------------------------------------------------------------+
| notify_candidate  | *boolean*        | - **true**: Sends a notification email to the candidate about the revoked invite.       |
| *(optional)*      |                  | - **false**: Revokes the invite silently without notifying the candidate.               |
+-------------------+------------------+-----------------------------------------------------------------------------------------+

Response
==========

- A JSON response indicating whether the revoke was successful or not.

Response Status Values
========================

+-------------------+-------------------------------------------------------------------------------------------------------------+
| Status            | Description                                                                                                 |
+===================+=============================================================================================================+
| REVOKED           | Invite was revoked successfully.                                                                            |
+-------------------+-------------------------------------------------------------------------------------------------------------+
| NOT_ALLOWED       | Invite cannot be revoked as it was sent before the latest plan change. Includes the relevant timestamp.     |
+-------------------+-------------------------------------------------------------------------------------------------------------+
| ALREADY_REVOKED   | The invite has already been revoked.                                                                        |
+-------------------+-------------------------------------------------------------------------------------------------------------+
| FAILED            | An error occurred while revoking the invite. The request should be retried later.                           |
+-------------------+-------------------------------------------------------------------------------------------------------------+

Examples
==========

**Example 1: Successful Revoke**

.. code-block:: JSON

    {
        "status": "REVOKED",
        "message": "Invite Revoked successfully."
    }

**Example 2: Not Allowed**

.. code-block:: JSON

    {
        "status": "NOT_ALLOWED",
        "message": "Invite was sent before the latest plan change",
        "timestamp": "2025-01-15 10:32:45"
    }

**Example 3: Already Revoked**

.. code-block:: JSON

    {
        "status": "ALREADY_REVOKED",
        "message": "Invite already revoked"
    }

**Example 4: Error While Revoking**

.. code-block:: JSON

    {
        "status": "FAILED",
        "message": "Error in revoking the invite. Please contact support"
    }