This documentation describes the end-to-end integration with the Maya AI Interview platform. The process follows a structured four-stage lifecycle:
\nInitialization: The client system triggers the Initialize Interview API, providing job requirements, candidate details, and skill weightages.
Invitation & Assessment: Upon successful initialization, an interview Url is generated. The platform sends an automated invitation to the candidate's emailId as per the configuration made during onboarding. The candidate then uses the link to attend the AI-driven session.
Report Generation: Once the candidate completes the assessment, the AI engine processes the responses to calculate the Weighted Report Score and generates a detailed performance report.
Asynchronous Notification: After the report is ready, the system automatically triggers a Maya Webhook. This sends a POST request to the payloadReceiverUrl provided during initialization, delivering the report link and final scores directly to your system only once but you can use Get Interview details api which provides same response as webhook payload.
Get Interview Details use this endpoint to retrieve the real-time status and metadata of a specific assessment using its interviewId.
Note: All x-api-key , ClientIds and maya url used here are dummy data use appropriate data provided during onboarding
If maya url is not provided during onboarding use \"ai.hireplusplus.com\"
Every API response from the Maya AI platform follows this standard wrapper:
\ndata (JSON Object): A generic container for the specific data requested or created by the API.
resultStatusInfo (JSON Object): Metadata confirming the success or failure of the operation.
resultStatusInfo ObjectProvides metadata about the API request processing itself.
\nresultCode (String): Indicates the outcome of the API call. Common values include SUCCESS, FAILURE.
message (String): A descriptive status message confirming the action taken (e.g., \"Successfully saved assessment info\").
This endpoint triggers the creation of a new AI interview session. It maps a candidate to a specific job role, defines the required skill sets and their relative importance, and sets the expiration for the interview link. It also configures the webhook where results will be sent once the session is complete.
\ncandidateName / emailld: The full name and contact email for the person being assessed.
candidateldentifier: A unique internal ID used to track the candidate in your system.
jobTitle / jdIdentifier: The name of the role and its specific unique job identifier.
interviewValidityDate: An ISO 8601 formatted string (e.g., 2025-06-17T09:47:14) defining when the interview link expires.
interviewSkillsData\")This list defines the technical scope of the AI interview:
\nskillName: The primary skill to be tested (e.g., \"CSS\" or \"JavaScript\"). These must be unique within the list.
subSkills: A list of specific topics within that skill (e.g., \"DOM manipulation\" or \"Box model\"). There is a maximum limit of 3 subskills per skill.
skillWeightage: An integer representing the importance of the skill. The total sum of all weightages in the request must equal 100.
configurationVariables: Contains the yearsOfExperience and the full jobResponsibilities text to help the AI tailor its questions.
mayaWebhookConfiguration: Includes the payloadReceiverUrl (where the result is sent) and a webhookSecret for secure authentication.
Once the request body is validated and the assessment is created, the data object provides the following session identifiers:
interviewId (String): The unique system-generated identifier for the session, used for all subsequent tracking.
interviewUrl (String): The direct link that must be shared with the candidate to begin their AI assessment.
This is an outbound service triggered by Maya AI. Once a candidate completes their assessment, Maya sends a real-time notification to your specified receiver URL. This payload contains the final weighted score, a link to the detailed web report, and any custom metadata (webhookNotes) originally sent during initialization.
interviewId: The unique reference ID for the specific session.
weightedReportScore: The final calculated score for the candidate based on their performance across all skills.
interviewCompletionDate: The timestamp in ISO 8601 format indicating when the candidate finished the assessment.
reportUrl: A direct link to the generated interview report.
reportData: An object containing the granular breakdown of the interview results.
webhookNotes: This object returns the exact key-value pairs (e.g., test, requid) that you originally provided during the initialization, allowing you to map the response back to your internal records.
A management endpoint used to poll the current status of an interview.
\ninterviewId: The unique reference ID for the specific session.StartFragment
\ninterviewId (String): The identifier confirming the record being viewed.
interviewState (String): The current progress status of the candidate (e.g., YET_TO_START, IN_PROGRESS, or COMPLETED).
interviewCompletionDate (String): The ISO 8601 timestamp indicating when the candidate submitted their final response.
reportUrl (String): The secure link to the detailed AI-generated performance report (available only after completion).
weightedReportScore (Number/Double): The final calculated score based on the candidate's proficiency and your defined skill weightages.