About iMochaHelpBook a demo
About iMochaHelpBook a demo
  1. Test Invitations
  • Introduction
  • Skills Assessment API
    • API Reference
      • Getting started
      • API Environment
      • Authentication Mechanism
      • Error Code
      • List timezones
    • Test
      • List all tests
      • Retrieve a test
      • Retrieve test settings
      • Update Test Settings
    • Test Invitations
      • Callback notification
      • Invite candidate
        POST
      • Invite candidate by test link
        POST
      • Reattempt Test
        POST
      • Cancel Invitation
        POST
    • Test Link
      • List all test links
    • Report
      • Retrieve candidate test report
      • Retrieve candidate test report in PDF
    • Callback API
      • Process Callbacks
      • Retrieve Invites
    • GDPR
      • GDPR Data Masking Service
    • Users
      • Get all business units
      • Create New User
      • Update User
      • Active/ Inactive User
  • Skills Intelligence API
    • Introduction
    • Authentication
    • Employee
      • List employees
      • Get Employee Skills by employeeId
      • Employee Enrollment
      • Update Employee Status
    • JobProfiles
      • Get All JobProfiles
      • Get JobProfile with Skills By JobProfileId
      • Create JobCode
    • Taxonomy
      • Get all Taxonomy Skills
    • CareerPath
      • Get Employee Career Path by employeeId
    • Account
      • Get Multichannel Validation Weightages
  1. Test Invitations

Invite candidate

POST
/v3/tests/{testId}/invite
🛠️ Registers candidate for given test using "Default test link".

API Behavior#

API will create "Default test link" in system for given test (if not present already), and all future invites (using this API) will apply configuration from default link.
By default, API does not send email to candidate.
This API is handy (kind of shortcut) in case you do not want to retrieve test link every single time just to send invites to candidate. If you wish to use specific test link to invite, check "Invite candidate by test link" API.
Original Invitation StatusInvite API Behavior
Invitation Pending (Test Attempt not taken)Invite API doesn't throw an error. It returns back the pending invitation. However it replaces the old Access time and timezoneid with the new details passed in the API request.
Invitation CancelledInvite API doesn't throw an error. It returns back the pending invitation. However it replaces the old Access time and timezoneid with the new details passed in the API request and changes the Invitation Status to Pending.
Invitation ExpiredInvite API doesn't throw an error. It returns back the pending invitation. However it replaces the old Access time and timezoneid with the new details passed in the API request and changes the Invitation Status to Pending.
Test Status - CompleteThe Invite API does not throw an error; instead, it returns the same invitation. However, if the candidate tries to retake the test, the platform will display a message stating: 'You have already attempted this test.' If you wish to allow the candidate to retake the same test, please use our Reattempt API.
Test Status - In ProgressInvite API doesn't throw an error. It returns the current invitation for which the Test is in Progress.
Test Status - Test LeftThe Invite API does not throw an error; instead, it returns the same invitation. However, if the candidate tries to retake the test, the platform will display a message stating: 'You have already attempted this test.' If you wish to allow the candidate to retake the same test, please use our Reattempt API.

Stakeholder Field#

Each test invitation has its own stakeholder email field, therefore every API call must include this field with the correct value in order to work as intended.
This will override stakeholder email for each individual invite. Not including this field will use the value present in the “Default test link”.

Request

Path Params

Header Params

Body Params application/json

Examples

Responses

🟢200OK
application/json
Body

Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request POST 'https://apiv3.imocha.io/v3/tests/{testId}/invite' \
--header 'x-api-key;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "string",
    "name": "string",
    "callbackUrl": "string",
    "redirectUrl": "string",
    "disableMandatoryFields": 0,
    "hideInstruction": 0,
    "sendEmail": "string",
    "stakeholderEmails": "string",
    "startDateTime": "string",
    "endDateTime": "string",
    "timeZoneId": 0,
    "ProctoringMode": "string"
}'
Response Response Example
{
    "testInvitationId": 0,
    "testUrl": "string",
    "status": "string"
}
Modified at 2025-09-10 10:27:11
Previous
Callback notification
Next
Invite candidate by test link
Built with