Analysis Events
Analysis events notify you when candidate analysis tasks are created and completed, when a workflow analysis re-scores an application, and when a workflow analysis can't score one.
Available Events
| Event | Description |
|---|---|
ANALYSIS_CREATED | A new analysis has been created |
CANDIDATE_ANALYSIS_COMPLETED | Analysis for a candidate is complete |
CANDIDATE_ANALYSIS_RESCORED | A workflow analysis re-scored an application before the workflow acted on its score (coming soon) |
CANDIDATE_ANALYSIS_RESCORED_AFTER_ACTED_ON | A workflow analysis re-scored an application after the workflow acted on its score (coming soon) |
CANDIDATE_ANALYSIS_FAILED | A workflow analysis could not score an application (coming soon) |
CANDIDATE_ANALYSIS_COMPLETED
Triggered when the analysis for an individual candidate is complete. This event includes the full analysis results including scores and requirement outcomes.
Payload
{
"event": "CANDIDATE_ANALYSIS_COMPLETED",
"eventId": "evt_abc123",
"eventTimestamp": "2024-01-15T10:30:00.000Z",
"data": {
"recordId": "candidate_xyz789",
"organizationId": "org_123456",
"atsApplicationId": "your_ats_application_id",
"externalId": "your_external_candidate_id",
"externalAnalysisId": "your_external_analysis_id",
"analysisCandidateUrl": "https://ai.joinpopp.com/ranks/{analysisId}?candidateId={candidateId}",
"totalScoreScaled": 0.86,
"isAllMandatoryRequirementsMet": true,
"requirementOutcomes": [
{
"requirement": "5+ years of software development experience",
"isMandatory": true,
"isMet": true,
"evidence": "Candidate has 7 years of experience as a Senior Software Engineer at Tech Corp"
},
{
"requirement": "Experience with React and TypeScript",
"isMandatory": true,
"isMet": true,
"evidence": "CV mentions 4 years of React development and TypeScript proficiency"
},
{
"requirement": "Leadership experience",
"isMandatory": false,
"isMet": false
}
]
}
}Data Fields
| Field | Type | Description |
|---|---|---|
atsApplicationId | string | Your ATS's ID for the application. null when the application did not come from your ATS |
externalId | string | Your external reference ID for the candidate |
externalAnalysisId | string | Your external reference ID for the analysis |
analysisCandidateUrl | string | Direct link to view the candidate in Popp |
totalScoreScaled | number | Overall score from 0 to 1, rounded to two decimal places, based on requirement matching |
isAllMandatoryRequirementsMet | boolean | Whether all mandatory requirements are satisfied |
requirementOutcomes | array | Detailed results for each requirement |
Requirement Outcome Object
| Field | Type | Description |
|---|---|---|
requirement | string | The original requirement text |
isMandatory | boolean | Whether this requirement is mandatory |
isMet | boolean | Whether the candidate meets this requirement |
evidence | string | Evidence from the CV (only present if isMet is true) |
Re-score events
A workflow analysis scores its applications again when a published version of the workflow changes the analysis node's requirements. Each re-scored application gets one of two events, depending on whether the workflow has acted on its score:
| Event | Sent when | What it means |
|---|---|---|
CANDIDATE_ANALYSIS_RESCORED | The workflow has not acted on the score yet | The new score replaces the application's score |
CANDIDATE_ANALYSIS_RESCORED_AFTER_ACTED_ON | The workflow has acted on an earlier score | The application keeps the score the workflow acted on. The new result is history only |
The workflow acts on a score when a run moves past the analysis node into a screening, engagement or scheduling outreach node, an Add to job node, or an Update ATS Application node, whether or not that node succeeds. From then on, the application keeps the score the workflow acted on.
Popp sends either event only when the new scaled score, or whether all mandatory requirements are met, differs from the application's previous score. After the workflow acts, the previous score can be an earlier re-score rather than the score the workflow acted on.
A re-score that produces no score sends CANDIDATE_ANALYSIS_FAILED with isRescore: true instead, and the application keeps the score it had.
In both events, data.recordId is the Candidate id, the same id CANDIDATE_ANALYSIS_COMPLETED carries for the application.
Delivery order
Re-scores, including a re-score's CANDIDATE_ANALYSIS_FAILED, are delivered apart from your other events, so re-scoring a large analysis doesn't delay them. A re-score can arrive before or after your other events for the same application.
Neither the order events arrive in nor eventTimestamp tells you which score is current. eventTimestamp is when Popp prepared the webhook, not when the application was scored.
When CANDIDATE_ANALYSIS_COMPLETED or CANDIDATE_ANALYSIS_RESCORED arrives for an application in a workflow, read the application's current score with Get workflow analysis application, using data.recordId as the candidateId. The events don't include the workflow id or the analysis node's slug, so take them from your own records: the workflow the application is in, and the slug you gave its analysis node. The example at the end of this page does this.
CANDIDATE_ANALYSIS_RESCORED
Coming Soon: This event is not yet available to subscribe to.
Triggered when a re-score changes an application's score before the workflow has acted on it. The new score replaces the application's score.
The payload has the same fields as CANDIDATE_ANALYSIS_COMPLETED. totalScoreScaled, isAllMandatoryRequirementsMet and requirementOutcomes are the application's new score, and analysisCandidateUrl links to the workflow in Popp.
Payload
{
"event": "CANDIDATE_ANALYSIS_RESCORED",
"eventId": "evt_def456",
"eventTimestamp": "2024-01-16T09:00:00.000Z",
"data": {
"recordId": "candidate_xyz789",
"organizationId": "org_123456",
"atsApplicationId": "your_ats_application_id",
"externalId": "your_external_candidate_id",
"externalAnalysisId": "your_external_analysis_id",
"analysisCandidateUrl": "https://app.joinpopp.com/workflows/{workflowId}",
"totalScoreScaled": 0.64,
"isAllMandatoryRequirementsMet": false,
"requirementOutcomes": [
{
"requirement": "5+ years of software development experience",
"isMandatory": true,
"isMet": true,
"evidence": "Candidate has 7 years of experience as a Senior Software Engineer at Tech Corp"
},
{
"requirement": "Experience leading a team of 5 or more engineers",
"isMandatory": true,
"isMet": false
}
]
}
}CANDIDATE_ANALYSIS_RESCORED_AFTER_ACTED_ON
Coming Soon: This event is not yet available to subscribe to.
Triggered when a re-score changes an application's result after the workflow has acted on an earlier score.
This event is history only. Nothing about the candidate changes: the application keeps actedOnScore, and rescore is what it scores against the newly published requirements. The payload has no top-level score, so neither can be read as the other. Because Popp compares a re-score with the application's previous score, rescore can equal actedOnScore.
Payload
{
"event": "CANDIDATE_ANALYSIS_RESCORED_AFTER_ACTED_ON",
"eventId": "evt_ghi789",
"eventTimestamp": "2024-01-16T09:00:00.000Z",
"data": {
"recordId": "candidate_xyz789",
"organizationId": "org_123456",
"atsApplicationId": "your_ats_application_id",
"externalId": "your_external_candidate_id",
"externalAnalysisId": "your_external_analysis_id",
"analysisCandidateUrl": "https://app.joinpopp.com/workflows/{workflowId}",
"actedOnScore": {
"totalScoreScaled": 0.86,
"isAllMandatoryRequirementsMet": true
},
"rescore": {
"totalScoreScaled": 0.64,
"isAllMandatoryRequirementsMet": false,
"requirementOutcomes": [
{
"requirement": "5+ years of software development experience",
"isMandatory": true,
"isMet": true,
"evidence": "Candidate has 7 years of experience as a Senior Software Engineer at Tech Corp"
},
{
"requirement": "Experience leading a team of 5 or more engineers",
"isMandatory": true,
"isMet": false
}
]
}
}
}Data Fields
| Field | Type | Description |
|---|---|---|
atsApplicationId | string | Your ATS's ID for the application. null when the application did not come from your ATS |
externalId | string | Your external reference ID for the candidate |
externalAnalysisId | string | Your external reference ID for the analysis |
analysisCandidateUrl | string | Direct link to the workflow in Popp |
actedOnScore | object | The score the workflow acted on. The application keeps this score |
actedOnScore.totalScoreScaled | number | Overall score from 0 to 1, on the same scale as CANDIDATE_ANALYSIS_COMPLETED. null when the workflow acted on a failed first score |
actedOnScore.isAllMandatoryRequirementsMet | boolean | Whether all mandatory requirements were met. null when the workflow acted on a failed first score |
rescore | object | The result against the newly published requirements. History only |
rescore.totalScoreScaled | number | Overall score from 0 to 1 against the new requirements |
rescore.isAllMandatoryRequirementsMet | boolean | Whether all mandatory requirements are met against the new requirements |
rescore.requirementOutcomes | array | The result for each requirement, as a Requirement Outcome Object |
CANDIDATE_ANALYSIS_FAILED
Coming Soon: This event is not yet available to subscribe to.
Triggered when a workflow analysis can't score an application. Popp sends it for a first score and for a re-score, and only for workflow analyses.
- A failed first score leaves the application with no score. The run follows the analysis node's
onAnalysisFailedroute, or fails if the node has none. See Branching on a failure. - A failed re-score leaves the application the score it had, and doesn't affect the run.
The payload has no score or requirement outcomes. data.recordId is the Candidate id, the same id the other analysis events carry for the application.
Payload
{
"event": "CANDIDATE_ANALYSIS_FAILED",
"eventId": "evt_jkl012",
"eventTimestamp": "2024-01-16T09:00:00.000Z",
"data": {
"recordId": "candidate_xyz789",
"organizationId": "org_123456",
"atsApplicationId": "your_ats_application_id",
"externalId": "your_external_candidate_id",
"externalAnalysisId": "your_external_analysis_id",
"analysisCandidateUrl": "https://app.joinpopp.com/workflows/{workflowId}",
"analysisErrorCode": "DOCUMENT_TOO_LARGE",
"isRescore": false
}
}Data Fields
| Field | Type | Description |
|---|---|---|
atsApplicationId | string | Your ATS's ID for the application. null when the application did not come from your ATS |
externalId | string | Your external reference ID for the candidate |
externalAnalysisId | string | Your external reference ID for the analysis |
analysisCandidateUrl | string | Direct link to the workflow in Popp |
analysisErrorCode | string | Why scoring failed. DOCUMENT_TOO_LARGE: the CV's text is too long to score. ANALYSIS_INPUT_UNAVAILABLE: there was no CV text and no screening answer to score. ANALYSIS_FAILED: scoring failed on Popp's side. More values may be added, so handle a value you don't recognise |
isRescore | boolean | false for a first score, which leaves the application with no score. true for a re-score, which leaves the application the score it had |
ANALYSIS_CREATED
Triggered when a new analysis is created.
Payload
{
"event": "ANALYSIS_CREATED",
"eventId": "evt_abc123",
"eventTimestamp": "2024-01-15T10:30:00.000Z",
"data": {
"recordId": "analysis_xyz789",
"organizationId": "org_123456"
}
}Example: Handling Analysis Events
interface RequirementOutcome {
requirement: string;
isMandatory: boolean;
isMet: boolean;
evidence?: string;
}
interface AnalysisScore {
totalScoreScaled: number;
isAllMandatoryRequirementsMet: boolean;
}
interface AnalysisWebhookData {
recordId: string;
organizationId: string;
externalId?: string;
externalAnalysisId?: string;
analysisCandidateUrl?: string;
totalScoreScaled?: number;
isAllMandatoryRequirementsMet?: boolean;
requirementOutcomes?: RequirementOutcome[];
// Both fields are null when the workflow acted on a failed first score
actedOnScore?: {
totalScoreScaled: number | null;
isAllMandatoryRequirementsMet: boolean | null;
};
rescore?: AnalysisScore & { requirementOutcomes: RequirementOutcome[] };
analysisErrorCode?: string;
isRescore?: boolean;
}
async function handleAnalysisWebhook(payload: {
event: string;
eventId: string;
eventTimestamp: string;
data: AnalysisWebhookData;
}) {
const { event, data } = payload;
switch (event) {
case 'ANALYSIS_CREATED':
console.log(`Analysis ${data.recordId} created`);
break;
case 'CANDIDATE_ANALYSIS_COMPLETED': {
const score = await getCurrentScore(data);
// Update your system with analysis results
updateCandidateRecord({
externalId: data.externalId,
score: score.totalScoreScaled,
passedScreening: score.isAllMandatoryRequirementsMet,
analysisUrl: data.analysisCandidateUrl,
});
// Auto-advance high-scoring candidates
if (score.totalScoreScaled && score.totalScoreScaled >= 0.8) {
moveToNextStage(data.externalId);
}
// Notify recruiters of qualified candidates
if (score.isAllMandatoryRequirementsMet) {
notifyRecruiter({
candidateUrl: data.analysisCandidateUrl,
score: score.totalScoreScaled,
});
}
break;
}
case 'CANDIDATE_ANALYSIS_RESCORED': {
// The re-score replaced the application's score
const score = await getCurrentScore(data);
updateCandidateRecord({
externalId: data.externalId,
score: score.totalScoreScaled,
passedScreening: score.isAllMandatoryRequirementsMet,
analysisUrl: data.analysisCandidateUrl,
});
break;
}
case 'CANDIDATE_ANALYSIS_RESCORED_AFTER_ACTED_ON':
// History only: the candidate keeps the score the workflow acted on
recordScoreHistory({
externalId: data.externalId,
score: data.rescore?.totalScoreScaled,
passedScreening: data.rescore?.isAllMandatoryRequirementsMet,
});
break;
case 'CANDIDATE_ANALYSIS_FAILED':
// A failed re-score leaves the score in place; a failed first score leaves none
recordScoringFailure({
externalId: data.externalId,
reason: data.analysisErrorCode,
isRescore: data.isRescore,
});
break;
}
}
// A workflow application's events can arrive out of order, so read its
// current score rather than saving the one in the event
async function getCurrentScore(data: AnalysisWebhookData) {
// Your record of the workflow and analysis node the application is in
const workflowAnalysis = findWorkflowAnalysis(data);
if (!workflowAnalysis) {
// Outside workflows, use the score in the event
return {
totalScoreScaled: data.totalScoreScaled,
isAllMandatoryRequirementsMet: data.isAllMandatoryRequirementsMet,
};
}
// GET /v1/workflows/{workflowId}/analyses/{workflowNodeSlug}/applications/{candidateId}
const application = await getWorkflowAnalysisApplication({
workflowId: workflowAnalysis.workflowId,
workflowNodeSlug: workflowAnalysis.workflowNodeSlug,
candidateId: data.recordId,
});
return {
totalScoreScaled: application.totalScoreScaled,
isAllMandatoryRequirementsMet: application.isAllRequirementsMet,
};
}Use Cases
- CRM Integration: Automatically update candidate records when analysis completes
- Scoring & Ranking: Trigger candidate ranking workflows based on analysis results
- Notifications: Alert recruiters when high-priority candidates are analyzed
- Auto-Screening: Automatically advance or reject candidates based on requirement outcomes
- Reporting: Track analysis metrics and qualification rates
Next Steps
- Analysis Guide - Complete guide to using the Analysis feature
- Webhooks Overview - Set up your webhook endpoints
Updated 28 days ago
