1. Fetch Test Details

This API allows programmatic retrieval of available or configured assessments, which can then be used for tagging candidates. Alternatively, the test details can be obtained manually (out-of-band) and configured directly on the ATS for tagging purposes.

Endpoint: https://ams.hirepro.in/v1/tests
Method: GET

Headers:
Authorization: Bearer <ACCESS_TOKEN>

Response:
[
  { "testId": "tmpl_01", "testName": "Frontend Developer - MCQ" },
  { "testId": "tmpl_02", "testName": "Data Science - Hands On" }
]

Details

• testId: Unique identifier for a test within HirePro.
• testName: Descriptive name or title of the test.

2. Register / Create Candidate & Tag to Test — POST /py/ats/v1/registerAndTagCandidateToTest/

Endpoint: https://ams.hirepro.in/py/ats/v1/registerAndTagCandidateToTest/
Method: POST
Headers: Authorization: Bearer <TOKEN>, X-APPLMA: true

Request body (JSON):
{
  "atsCandidateId": "ats_12345",         // optional
  "primaryEmail": "john.doe@example.com", // mandatory
  "phoneNumber": "+919876543210",        // mandatory
  "testId": "tmpl_01",                   // mandatory (HirePro testId)
  "firstName": "John",
  "middleName": "M",
  "lastName": "Doe",
  "profilePhoto": "",        // optional
  "gender": "male|female|other",          // optional
  "dob": "DD/MM/YYYY"                     // optional
}

Success response (sample):
{
  "status": "OK",
  "data": {
    "testUserGuid": "988a3269-1f45-4f27-ac11-837d8468294e",
    "HireProCandidateId": 54321,
    "message": "Candidate registered and tagged",
    "isDuplicateCandidate": false,
    "tagged2TestAlready": false
  }
}

Response field details

• isDuplicateCandidate: Indicates whether the provided ATS Candidate Id or email already exists in HirePro.
• HireProCandidateId: Unique HirePro candidate id assigned to the record.
• tagged2TestAlready: True if the candidate was already associated to the given test.
• message: Optional human-friendly message.

Notes

• Email is the primary unique key used for duplicate checks.
• If name fields are missing, ATS Candidate Id may be used as a fallback display name — provide proper names where possible to ensure personalized communications.

1. Send Assessment Details back to ATS — TEST_USER_ASSESSMENT_SCORED

After candidate answer the evaluation, HirePro will POST results to your configured ATS callback URL.

Endpoint: <your_ats_callback_url>
Method: POST
Headers:
  Content-Type: application/json

Body (JSON):
{
  "testUserGuid": "988a3269-1f45-4f27-ac11-837d8468294e",
  "eventName": "TEST_USER_ASSESSMENT_SCORED",
  "eventData": {
    "testScore": 78.5,
    "vTestStatus": "TestScored", // or "TestNotScored"
    "vTestReport": "https://vendor.example.com/vtest/123",
    "scoreReport": "https://hirepro.com/reports/asm_123",
    "proctorReviewReport": "https://hirepro.com/proctor/asm_123",
    "suspicionLevelAsPerAI": "Low|Medium|High|Not Suspicious|Not Evaluated",
    "suspicionLevelAsPerManualReview": "Suspicious|Not Suspicious|Not Evaluated|May Be Suspicious",
    "scoreDetails": [
      {
        "groupName": "Logical Reasoning",
        "candidateScoreTotal": 35.0,
        "maxMarks": 50.0,
        "sectionInfos": [
          { "sectionName": "Section A", "candidateScoreTotal": 20.0, "maxMarks": 25.0 },
          { "sectionName": "Section B", "candidateScoreTotal": 15.0, "maxMarks": 25.0 }
        ]
      }
    ],
    "manualReviewComment": "Handwriting unclear in Q2"
  }
}

Notes & Field Explanations

• vTestStatus: "TestNotScored" indicates no score could be generated (e.g., unreadable answers).
• vTestReport: External vendor test report link (e.g., Versant).
• scoreReport: HirePro-hosted candidate report link (requires login/SSO to view).
• scoreDetails: Optional detailed breakdown. If present, include only if your ATS needs section-level data.
• proctorReviewReport: Link to proctoring video/review (requires login).
• Ignore any additional/unexpected fields unless agreed otherwise between HirePro and ATS.

Callback Behaviour — retries & multiple firings

This callback may be triggered multiple times. Typically, AI proctoring evaluation completes earlier and a callback is sent. Manual review (if service taken) may complete later and trigger a second callback with updated manual review fields.

• If the ATS returns HTTP 200 OK, the callback is presumed to be handled at the ATS and no further attempts are made for the given event type.
• During initial callback/manualReview pending, fields like suspicionLevelAsPerManualReview may be set to "Not Evaluated" and updated later.