Analysis Events

Analysis events notify you when candidate analysis tasks are created and completed.

Available Events

Event	Description
`ANALYSIS_CREATED`	A new analysis has been created
`CANDIDATE_ANALYSIS_COMPLETED`	Analysis for a candidate is complete

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",
    "externalId": "your_external_candidate_id",
    "externalAnalysisId": "your_external_analysis_id",
    "analysisCandidateUrl": "https://ai.joinpopp.com/ranks/{analysisId}?candidateId={candidateId}",
    "totalScoreScaled": 85.5,
    "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
`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 AI
`totalScoreScaled`	number	Overall score (0-100) 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`)

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 AnalysisWebhookData {
  recordId: string;
  organizationId: string;
  externalId?: string;
  externalAnalysisId?: string;
  analysisCandidateUrl?: string;
  totalScoreScaled?: number;
  isAllMandatoryRequirementsMet?: boolean;
  requirementOutcomes?: RequirementOutcome[];
}

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':
      // Update your system with analysis results
      updateCandidateRecord({
        externalId: data.externalId,
        score: data.totalScoreScaled,
        passedScreening: data.isAllMandatoryRequirementsMet,
        analysisUrl: data.analysisCandidateUrl,
      });

      // Auto-advance high-scoring candidates
      if (data.totalScoreScaled && data.totalScoreScaled >= 80) {
        moveToNextStage(data.externalId);
      }

      // Notify recruiters of qualified candidates
      if (data.isAllMandatoryRequirementsMet) {
        notifyRecruiter({
          candidateUrl: data.analysisCandidateUrl,
          score: data.totalScoreScaled,
        });
      }
      break;
  }
}

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