*********************************************
``POST`` Invite Candidate to an AI Interview
*********************************************

This API invites a candidate to the specified AI Interview by returning the Invite Link.

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

.. code-block::

    POST /ai-interviews/invite

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

.. code-block:: JSON

    {
        "candidate_name": "string",
        "candidate_email": "string",
        "ai_interview_id": "integer",
        "invite_format": "string",
        "start_date": "string",
        "expiry_date": "string",
        "custom_field_id": "string"
    }

.. warning::

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

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

+-------------------+------------------+-----------------------------------------------------------------------------------------------------+
| Parameter         | Type             | Description                                                                                         |
+===================+==================+=====================================================================================================+
| candidate_name    | *string*         | The name of the candidate whom you want to invite to the AI Interview.                              |
+-------------------+------------------+-----------------------------------------------------------------------------------------------------+
| candidate_email   | *string*         | The email of the candidate whom you want to invite to the AI Interview.                             |
+-------------------+------------------+-----------------------------------------------------------------------------------------------------+
| invite_format     | *enum*           | - **getlink**: This option will only create an invite link for the candidate which can be shared.   |
|                   |                  | - **sendlink**: This option will send an invite to the candidate via email.                         |
+-------------------+------------------+-----------------------------------------------------------------------------------------------------+
| ai_interview_id   | *integer*        | The AI Interview ID to which you want to invite the candidate.                                      |
+-------------------+------------------+-----------------------------------------------------------------------------------------------------+
| start_date        | *string*         | - The start time from which the candidate is allowed to access the interview.                       |
| *(optional)*      |                  | - Format: **YYYY-MM-DD HH:MM** (in **GMT**)                                                         |
|                   |                  |                                                                                                     |
|                   |                  | **Example:** 2025-07-14 12:00                                                                       |
+-------------------+------------------+-----------------------------------------------------------------------------------------------------+
| expiry_date       | *string*         | - Expiry Date and Time for the Invite Link.                                                         |
| *(optional)*      |                  | - Format: **YYYY-MM-DD HH:MM** (in **GMT**)                                                         |
|                   |                  |                                                                                                     |
|                   |                  | **Example:** 2025-07-16 23:59                                                                       |
+-------------------+------------------+-----------------------------------------------------------------------------------------------------+
| custom_field_id   | *string*         | - A custom identifier for tracking this candidate in your system.                                   |
| *(optional)*      |                  | - Can be used later to fetch the report via ``GET /ai-interviews/report?custom_field_id=<value>``   |
+-------------------+------------------+-----------------------------------------------------------------------------------------------------+

.. note::

    - Both ``start_date`` and ``expiry_date`` must be provided in **GMT** timezone.
    - If these values are omitted, the invite will be immediately active and has no expiry.

Response
==========

- A JSON response containing information about the Candidate Invite and AI Interview Link.

.. code-block:: JSON

    {
        "email": "string",
        "ai_interview_id": "integer",
        "ai_interview_name": "string",
        "response_id": "integer",
        "invite_link": "string",
        "name": "string",
        "status": "string",
        "custom_field_id": "string"
    }

- A JSON error response when invites are exhausted.

**Status Code:** ``403 Forbidden``

.. code-block:: JSON

    {
        "message": "Invites Exhausted. Please contact support.",
        "error": "limit_exceed"
    }

Examples
==========

**Request Payload**

.. code-block:: JSON

    {
        "candidate_name": "alex tanaka",
        "candidate_email": "alex.tnk@example.com",
        "ai_interview_id": 305,
        "invite_format": "getlink",
        "start_date": "2025-07-18 10:00",
        "expiry_date": "2025-07-20 20:30",
        "custom_field_id": "CAND-2025-001"
    }

**Success Response**

.. code-block:: JSON

    {
        "email": "alex.tnk@example.com",
        "ai_interview_id": 305,
        "ai_interview_name": "Senior Data Engineer",
        "response_id": 7421,
        "invite_link": "https://your-subdomain.xobin.com/app/copilot/interview/cl/1A2B3C4D5E?inviteToken=F84E3D22AC91B73F8E65C92AE3DF7D6284BC9AD1B6A5CE9C02C1F13A45C6798F",
        "name": "alex tanaka",
        "status": "Invite Link created",
        "custom_field_id": "CAND-2025-001"
    }

**Error Response (Invites Exhausted)**

.. code-block:: JSON

    {
        "message": "Invites Exhausted. Please contact support.",
        "error": "limit_exceed"
    }