*******************************************
``POST`` Parse Candidate Resume
*******************************************

This API parses a candidate's resume, extracts structured information, and optionally evaluates the candidate's fitment against a provided Job Description (JD). A new candidate profile is also created in Xobin, and the API returns a link to the uploaded resume along with the parsed details.

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

.. code-block::

    POST /candidate/resume/parse

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

.. code-block:: JSON

    {
        "resume": "string",
        "job_description": "string",
        "only_parse": "boolean",
        "criteria": "string"
    }

.. warning::

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

.. note::

    This endpoint consumes an **AI Evaluate call**.  
    The requesting company must have access to the **AI Evaluate** feature.  
    If the feature is not enabled, the API will return a ``403 FORBIDDEN`` response.

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

+-------------------+-------------------------+-----------------------------------------------------------------------------------------------------+
| Parameter         | Type                    | Description                                                                                         |
+===================+=========================+=====================================================================================================+
| resume            | string                  | URL of the resume file to be processed.                                                             |
+-------------------+-------------------------+-----------------------------------------------------------------------------------------------------+
| only_parse        | boolean *(optional)*    | If **true**, only the parsed resume details are returned.                                           |
|                   |                         | If **false** (default), fitment scoring is also performed.                                          |
+-------------------+-------------------------+-----------------------------------------------------------------------------------------------------+
| job_description   | string *(conditional)*  | Job description text used for fitment evaluation.                                                   |
|                   |                         | Required only if ``only_parse`` is **false**. Can be omitted if ``only_parse`` is **true**.         |
+-------------------+-------------------------+-----------------------------------------------------------------------------------------------------+
| criteria          | string *(conditional)*  | Criteria text for fitment evaluation.                                                               |
|                   |                         | Required only if ``only_parse`` is **false**. Can be omitted if ``only_parse`` is **true**.         |
+-------------------+-------------------------+-----------------------------------------------------------------------------------------------------+

Response
==========

- A JSON response containing the parsed candidate resume details, candidate ID, resume link, and (if applicable) fitment evaluation.

.. code-block:: JSON

    {
        "candidate_id": "integer",
        "resume_link": "string",
        "parsed_resume": {
            "name": "string",
            "email": "string",
            "phone": "string",
            "applied_for": "string",
            "educational_qualification": [
                {
                    "degree": "string",
                    "gpa": "float",
                    "graduation_year": "integer",
                    "institution": "string",
                    "summary": "string"
                }
            ],            
            "highlights": ["string"],
            "interview_questions": ["string"],
            "location": "string",
            "other_suitable_roles": ["string"],
            "skills": ["string"],
            "summary": "string",
            "work_experience": [
                {
                    "company": "string",
                    "position": "string",
                    "start_year": "integer",
                    "end_year": "integer",
                    "duties": ["string"]
                }
            ]
        },
        "fitment_score": "integer",           // only if only_parse = false
        "fitment_reason": "string"            // only if only_parse = false
    }

- If the resume parsing fails, the API will return a JSON response with the error message. The response will have the following format:

.. code-block:: JSON

    {
        "error": "error message"
    }