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

EventDescription
ANALYSIS_CREATEDA new analysis has been created
CANDIDATE_ANALYSIS_COMPLETEDAnalysis for a candidate is complete
CANDIDATE_ANALYSIS_RESCOREDA workflow analysis re-scored an application before the workflow acted on its score (coming soon)
CANDIDATE_ANALYSIS_RESCORED_AFTER_ACTED_ONA workflow analysis re-scored an application after the workflow acted on its score (coming soon)
CANDIDATE_ANALYSIS_FAILEDA 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

FieldTypeDescription
atsApplicationIdstringYour ATS's ID for the application. null when the application did not come from your ATS
externalIdstringYour external reference ID for the candidate
externalAnalysisIdstringYour external reference ID for the analysis
analysisCandidateUrlstringDirect link to view the candidate in Popp
totalScoreScalednumberOverall score from 0 to 1, rounded to two decimal places, based on requirement matching
isAllMandatoryRequirementsMetbooleanWhether all mandatory requirements are satisfied
requirementOutcomesarrayDetailed results for each requirement

Requirement Outcome Object

FieldTypeDescription
requirementstringThe original requirement text
isMandatorybooleanWhether this requirement is mandatory
isMetbooleanWhether the candidate meets this requirement
evidencestringEvidence 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:

EventSent whenWhat it means
CANDIDATE_ANALYSIS_RESCOREDThe workflow has not acted on the score yetThe new score replaces the application's score
CANDIDATE_ANALYSIS_RESCORED_AFTER_ACTED_ONThe workflow has acted on an earlier scoreThe 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

FieldTypeDescription
atsApplicationIdstringYour ATS's ID for the application. null when the application did not come from your ATS
externalIdstringYour external reference ID for the candidate
externalAnalysisIdstringYour external reference ID for the analysis
analysisCandidateUrlstringDirect link to the workflow in Popp
actedOnScoreobjectThe score the workflow acted on. The application keeps this score
actedOnScore.totalScoreScalednumberOverall score from 0 to 1, on the same scale as CANDIDATE_ANALYSIS_COMPLETED. null when the workflow acted on a failed first score
actedOnScore.isAllMandatoryRequirementsMetbooleanWhether all mandatory requirements were met. null when the workflow acted on a failed first score
rescoreobjectThe result against the newly published requirements. History only
rescore.totalScoreScalednumberOverall score from 0 to 1 against the new requirements
rescore.isAllMandatoryRequirementsMetbooleanWhether all mandatory requirements are met against the new requirements
rescore.requirementOutcomesarrayThe 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 onAnalysisFailed route, 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

FieldTypeDescription
atsApplicationIdstringYour ATS's ID for the application. null when the application did not come from your ATS
externalIdstringYour external reference ID for the candidate
externalAnalysisIdstringYour external reference ID for the analysis
analysisCandidateUrlstringDirect link to the workflow in Popp
analysisErrorCodestringWhy 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
isRescorebooleanfalse 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


Did this page help you?