Mapping JobCannon Scores to iCIMS Fields
Technical guide to parsing JobCannon assessment results in iCIMS and mapping dimensions to scorecard fields via iCIMS Connect API.
Mapping JobCannon Scores to iCIMS Fields
When a candidate completes a JobCannon assessment in iCIMS, the result is returned via the iCIMS Connect API. This guide explains how to parse results and update scorecard fields.
Callback Payload Structure
When assessment is complete, JobCannon sends a POST callback to iCIMS Connect API:
{
"eventType": "assessment.completed",
"timestamp": "2026-05-17T14:32:00Z",
"candidateId": "c_12345",
"assessment": {
"id": "assess_abc123",
"name": "Big Five",
"slug": "big-five",
"completed_at": "2026-05-17T14:32:00Z",
"duration_seconds": 245,
"result": {
"status": "complete",
"overall_score": 72,
"overall_percentile": 65,
"dimensions": [
{
"name": "Openness",
"score": 68,
"percentile": 65,
"interpretation": "above_average"
},
{
"name": "Conscientiousness",
"score": 81,
"percentile": 78,
"interpretation": "high"
}
],
"metadata": {
"faking_detected": false,
"social_desirability_scale": 32
},
"profile_url": "https://app.jobcannon.io/results/[session-id]"
}
}
}
Parsing the Assessment Result
Here's a TypeScript example to extract and map assessment results:
interface iCIMSAssessmentPayload {
eventType: string
candidateId: string
assessment: {
name: string
result: {
overall_score: number
overall_percentile: number
dimensions: Array<{ name: string; score: number; percentile: number }>
metadata: { faking_detected: boolean; social_desirability_scale: number }
}
}
}
async function processICIMSAssessment(payload: iCIMSAssessmentPayload) {
const { candidateId, assessment } = payload
// Build scorecard field updates
const scorecardUpdates = {
jc_assessment_name: assessment.name,
jc_overall_score: assessment.result.overall_score,
jc_overall_percentile: assessment.result.overall_percentile,
jc_faking_risk: assessment.result.metadata.social_desirability_scale,
jc_profile_url: assessment.result.profile_url
}
// Map each dimension
assessment.result.dimensions.forEach(dim => {
const fieldName = `jc_${dim.name.toLowerCase().replace(/\s+/g, '_')}`
scorecardUpdates[`${fieldName}_score`] = dim.score
scorecardUpdates[`${fieldName}_percentile`] = dim.percentile
})
// Update candidate scorecard via iCIMS Connect API
await updateCandidateScorecard(candidateId, scorecardUpdates)
}
Scorecard Field Mapping
Create the following custom fields in iCIMS before deploying:
| Field | Type | Purpose ||---|---|---|| jc_assessment_name | Text | Assessment type (e.g., "Big Five") || jc_overall_score | Number | Aggregate score (0–100) || jc_overall_percentile | Number | Percentile rank (0–100) || jc_[dimension]_score | Number | Score per dimension || jc_[dimension]_percentile | Number | Percentile per dimension || jc_faking_risk | Number | Social desirability (0–100) || jc_profile_url | URL | Link to full result |iCIMS Connect API Update
Update candidate scorecard via PATCH request:
PATCH /connect/api/v1/candidates/{candidateId}/scorecard
Authorization: Bearer [iCIMS-Connect-Token]
Content-Type: application/json
{
"fields": {
"jc_assessment_name": "Big Five",
"jc_overall_score": 72,
"jc_overall_percentile": 65,
"jc_openness_score": 68,
"jc_openness_percentile": 65,
"jc_conscientiousness_score": 81,
"jc_conscientiousness_percentile": 78,
"jc_faking_risk": 32
}
}
Response:
{
"candidateId": "c_12345",
"status": "updated",
"timestamp": "2026-05-17T14:32:30Z"
}
Webhook Delivery and Retry
If scorecard update fails, JobCannon retries with exponential backoff:
Logs are available in JobCannon admin (/admin/integrations/icims/logs).
Handling Edge Cases
Candidate Abandoned Assessment
If the candidate closes the browser before submitting, no webhook is triggered. The recruiter must re-send the assessment from iCIMS or move the candidate to the next stage.
Faking Detected (Social Desirability > 70)
Flag the result for review:
if (payload.assessment.result.metadata.social_desirability_scale > 70) {
await addCandidateNote(candidateId, {
type: 'assessment_review_needed',
message: 'Assessment flagged for possible response bias. Consider re-testing.'
})
}
EEOC Compliance
Use percentile ranks for adverse-impact analysis (not raw scores):
const whitePassRate = (passCount / totalWhite)
const blackPassRate = (passCount / totalBlack)
if ((blackPassRate / whitePassRate) < 0.8) {
console.warn('Potential adverse impact detected')
}
---
**Vendor docs:** https://www.icims.com/developers/api
**Scorecard API:** https://www.icims.com/connect/scorecard
**Support:** [email protected]