*******************************************
``POST`` Revoke Candidate Assessment Invite
*******************************************

This API revokes a candidate's invite for a specified Assessment.

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

.. code-block::

    POST /assessments/invite/revoke

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

.. code-block:: JSON

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

.. warning::

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

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

+-------------------+------------------+-----------------------------------------------------------------------------------------+
| Parameter         | Type             | Description                                                                             |
+===================+==================+=========================================================================================+
| report_id         | *integer*        | The Report 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.                                                                        |
+-------------------+-------------------------------------------------------------------------------------------------------------+
| ERROR_REVOKING    | 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: Error While Revoking**

.. code-block:: JSON

    {
        "status": "ERROR_REVOKING",
        "message": "Unable to Revoke invite now, Please try again later."
    }